Sopheons

If this is your first visit

1. Select Open Memory.
2. Choose an existing physical folder or portable vault. If you do not have one, select This is my first time and let Sopheons explain both storage choices.
3. After the memory opens, go to Build Memory. Add a note, project, file, URL, or useful conversation.
4. Use Update Memory when you want AI to analyse source material. Review every proposal before accepting it.
5. When there is enough useful context for a task, go to Orchestrate → New Run.

If you want to add or refresh knowledge

Follow Build Memory → Add Memory or Add Sources → Update Memory → review proposals. Use Check Memory first when files were changed outside Sopheons. You can stop after applying the accepted changes; there is no need to create a run.

If you are ready to start a piece of work

Follow Orchestrate → New Run → Work → Workflow → Context → Run Pack. Choose one project and describe one concrete outcome. Review the selected memory, build the Run Pack, then copy it into your preferred agent. You can skip Update Memory if the existing knowledge is already current enough for the task.

After the work is complete

Open Run History, record the result and status, and prepare a follow-up if needed. If the work produced a lasting decision, correction, preference, or project change, return to Build Memory and add it. Temporary output does not need to become permanent memory.

Keep this distinction clear: memory is the durable knowledge you may reuse; a Run Pack is the focused instruction and context package for one piece of work.

Physical folder mode

This is the recommended desktop workflow when other local tools, including Codex or OpenCode, should be able to see and edit individual Markdown files. Memory nodes are physical files under folders such as nodes/; raw imports live under sources/; generated briefs live under briefs/; and rebuildable indexes live under data/.

When the app says it saved briefs/example.md in folder mode, that should be a real file in the selected folder. Finder, terminal tools, editors, and permitted LLM clients can access it directly.

Portable vault mode

A portable vault stores the memory inside one .memory.json file. Paths such as nodes/projects/example.md or briefs/example.md are internal paths inside that vault. They are not automatically separate sibling files in Finder. Use this mode when a single portable file is preferable, especially through mobile Files providers.

After making changes in vault mode, use Save Memory when required. A successful in-app edit is only durable across reopening when the updated vault itself has been written to the selected file location.

Local versus synced storage

Sopheons does not require its own cloud. A physical folder or vault can live locally, or in a folder synchronised by iCloud Drive, Proton Drive, Google Drive, Dropbox, or another provider. The sync provider moves the files; Sopheons reads and writes the memory format.

Do not keep two independent copies active unless you deliberately manage the difference. If a live folder and an older vault disagree, the copy you actually opened determines what the app can see.

The Library lists memory nodes. A node is a focused Markdown record with frontmatter and a readable body. Nodes can represent projects, sources, concepts, evidence, observations, analyses, decisions, principles, risks, tasks, stages, components, notes, and blueprints.

• Search your memory filters by title, ID, tags, source references, filename, and body content.
• Browse by type narrows the result set without changing any files.
• Ask AI can interpret a natural-language description and suggest relevant nodes when a provider is configured.
• Write Note creates a new node. Use a clear title, focused body, useful tags, and related node IDs when known.
• Edit Selected updates the selected node in the opened memory.
• Add Project creates project memory; Register Project Folder connects an existing working folder as a reference when supported.

Use one node for one durable idea or responsibility when practical. Avoid enormous catch-all nodes. Focused nodes are easier to search, connect, update, and select for Run Packs.

Draft describes workflow maturity, not whether a file was saved. A draft node may already be safely stored. Saving and status are different concepts.

A source is the material from which durable memory may be extracted. It can be a note, document, webpage, project file, conversation export, email reference, repository reference, or another piece of evidence.

Apple Notes and Markdown

On current Apple systems, Notes can import a Markdown file and export a note as Markdown. Importing creates a Notes copy and exporting creates a new .md file; it does not keep one canonical file synchronized. Use an exported Notes file as a source in Sopheons, or prepare a checklist in Sopheons and open the exported Markdown in Notes.

Imported files normally enter the raw sources/ area first. Sopheons preserves the original where possible and creates Markdown-ready extracted text. A raw file may therefore exist before a matching source node has been created. Sopheons should recognise this as material that still needs ingest or analysis.

What should become permanent memory?

Prefer durable signal: confirmed facts, decisions, explicit corrections, stable preferences, reusable explanations, project structure, risks, principles, tasks, and important evidence. Avoid copying complete chats into permanent concept nodes. Conversation exports are temporary evidence; review the proposed learnings before writing them.

Freshness

Source freshness compares when the source was last changed with when it was last analysed. If the source timestamp is newer than analyzed_at, its analysis may be stale. Updating the source file does not automatically mean the derived concepts are current.

References such as URLs, local paths, repositories, Drive documents, or emails may not be duplicated fully. Their nodes should retain enough location and timestamp information to support later freshness checks.

Update Memory is the automatic analysis workflow. It is different from creating a Run Pack. Updating changes durable memory after your review; a Run Pack selects existing memory for one external task.

1. The app checks for new raw files, source nodes that have never been analysed, and sources whose content is newer than their last analysis.
2. The selected configured provider receives the relevant source content and extraction instructions.
3. The provider proposes new nodes, updates to existing nodes, source timestamps, and useful links.
4. You review every proposed item. New nodes show their type, title, links, sources, and complete Markdown; existing updates show the exact addition. Accept, edit, or reject each item. Duplicate IDs, missing sources, unsupported types, and broken links are highlighted before writing.
5. When you choose Apply accepted batch, the app validates the complete batch, creates a pre-update backup, writes only accepted items, rebuilds data/graph.json, updates the portable vault when one is in use, and verifies the node IDs and counts in every relevant storage format. If any stage fails, changed files are restored automatically.

Keep the update window open while analysis is running. Large documents or several sources may take time. If no update is offered, use Check Memory and confirm that the files were added inside the memory you actually opened.

Conversation learning follows the same review rule. Importing a Codex, OpenCode, ChatGPT, Claude, JSON, JSONL, Markdown, or text export does not make the transcript permanent. The provider should extract only durable signal.

A Run Pack is one standalone Markdown instruction artifact for a specific piece of work. New Run is only for creating that pack. Run History is only for reopening saved packs and recording what happened afterward.

Creating a new run

1. Work: choose the project, target agent, expected output, and one concrete task with its completion condition.
2. Workflow: choose a preset or select reusable blocks such as Inspect, Implement, Test, Git, Deploy, Verify, Memory, and Return result. This happens inside New Run; there is no separate process-selection page.
3. Context: review the relevant memory selected for this run and any source-freshness warning.
4. Run Pack: generate the one final instruction artifact, then copy it to Codex or OpenCode, download it, or save it to Run History.

Run History

Use Run History after saving a Run Pack or receiving an agent result. You can reopen the Markdown, change its status, paste the result back, and prepare a follow-up. Files remain under the compatible briefs/ storage path, but they are presented as saved runs rather than a second builder.

Optional memory maintenance

The collapsed source-memory tools in New Run are for analysing stale source material. They do not create a competing Run Pack and can be ignored when the selected memory is already current.

Graph

The Graph visualises relationships between nodes. Confirmed links come from node metadata; inferred links are suggestions based on references and text. Search a topic, select a neighbour depth, filter node types, and inspect the relevant neighbourhood. Re-layout changes the visual arrangement, while saving the graph index writes the rebuildable data/graph.json file. Use Rebuild and verify memory after external edits to regenerate the graph, refresh an existing portable vault, validate the repository, and compare exact node IDs across storage formats.

Use Add idea node for a standalone thought. Select a graph node and choose Add connected idea to grow a new concept from it, or Connect existing nodes to draw a durable relationship between two ideas that are already in memory. Reciprocal linking writes the relationship into both nodes.

Links

Suggested links are not automatically treated as confirmed truth. Review them, accept useful connections, and reject misleading ones. Reciprocal links can make navigation clearer when both nodes genuinely relate to each other.

To build a network by hand, create or open the first node, then choose Add connected node. Pick a template such as Concept, Decision, Task, Blueprint, or Source. The new node starts with the selected node in Related; keep reciprocal linking checked to write the connection into both nodes.

Blueprints

A blueprint is the obvious planning home for a project. It can record the current goal, temporal plan, structure, completed work, missing or weak areas, decisions to preserve, decisions to reconfirm, risks, questions, and the suggested next step. Use it to avoid hiding the project plan across miscellaneous notes and old briefs.

Review

Review reports repository problems such as duplicate IDs, broken related links, malformed metadata, or unreadable structures. Generated indexes should be rebuildable from the Markdown source of truth; do not treat an index as the only copy of important memory.

Sopheons is LLM and client agnostic. Run Packs can be used with Codex, ChatGPT, Claude, OpenCode, OpenRouter, GLM5.2, Nemotron 3, DeepSeek, local models, and other tools that accept text or Markdown.

An API key is optional for opening, browsing, editing, searching normally, exporting prompts, and manually using Run Packs. A configured provider is needed for automatic source analysis, semantic AI search, or direct LLM-assisted generation.

• In the local macOS app, supported keys are stored in Mac Keychain rather than the memory repository or browser storage.
• In the hosted app, provider keys belong in protected server environment configuration or the protected server-side LLM configuration file—not inside public JavaScript or the user’s memory.
• When analysis uses an external provider, the selected source content and instructions are sent to that provider. Merely opening the memory does not upload the folder.
• The hosted website does not need to store the user’s memory. The browser opens the selected folder or vault, and the user controls saving.

Passkeys protect access to the hosted application. Passkeys are domain-bound and may also depend on the device, browser profile, or password manager where they were created. Logging out clears the application session; it does not delete the memory or the passkey itself.

I opened memory but cannot see my nodes.

Confirm that you opened the correct physical folder or the current vault file. Use Check Memory. If using a vault, remember that files placed beside the vault are not automatically inside it.

I added a file, but Update Memory says nothing needs analysis.

Confirm the file is inside the opened memory’s sources/ area, then use Check Memory. The app must detect either a raw source needing ingest or a source node whose analysis is missing or stale.

The search result is missing something I know exists.

Search also considers node body text. First verify that the node exists in the memory copy currently open. A stale portable vault may not contain newer files from a physical folder.

My saved run is not visible in Finder.

Check the storage mode. In physical folder mode its compatible storage path is briefs/. In portable vault mode it is an internal path until exported, and the vault itself must be saved.

The app says a node is Draft even though I saved it.

Draft is a workflow status, not a save failure. Verify the save message and storage location separately.

Update Memory is taking a long time.

Keep the window open and review the progress message. Large sources and external providers can take time. Avoid closing or refreshing during an active update.

The provider returned invalid JSON or an error.

Retry after checking provider status in Settings. Provider output can occasionally be malformed. If the problem repeats, note the provider, model, visible error, and start of the response when shown.

An API call returns a web page instead of data.

The browser may be reaching a stale local server or an incorrect hosted endpoint. Refresh the active application/server deployment and verify that the PHP API files are uploaded in the correct api/ directory.

My passkey does not work after a domain change.

A passkey created for one domain cannot authenticate another domain. Register a new passkey on the new domain. Do not overwrite the passkey database when deploying code changes.

Markdown, graph, and vault node counts disagree.

Open the physical folder that contains the newest Markdown, then use Rebuild and verify memory. The app rebuilds data/graph.json, refreshes an existing memory-vault.memory.json, validates the repository, and confirms the exact node IDs and totals.

I changed files outside Sopheons.

Use Rebuild and verify memory to reload the selected memory, regenerate its derived storage, and confirm that the formats agree before trusting search, graph, freshness, or Run Pack selection.

Memory repository

The user-owned collection of Markdown nodes, sources, briefs, and rebuildable data files.

Node

A focused durable Markdown record representing a source, concept, decision, project, task, risk, blueprint, or another memory type.

Source

Raw or referenced evidence from which durable memory may be extracted.

Analysis

The reviewed process of extracting useful concepts, decisions, risks, and links from source material.

Run Pack

The single focused instruction and context package sent to an execution agent for one run.

Blueprint

The central planning node for a project’s goal, structure, decisions, current state, and next work.

Physical folder

A real filesystem directory containing individually visible Markdown files.

Portable vault

A single JSON file containing the repository’s internal file paths and content.

Freshness

Whether derived memory was analysed after the latest known change to its source.

Questions you can copy into your LLM

• “I am new to Sopheons. Walk me through creating my first memory and first Run Pack.”
• “Should I use a physical folder or a portable vault for my devices and workflow?”
• “I imported several documents. Explain exactly what I should do next and why.”
• “Help me design good node types and links for this project.”
• “Why is my source marked stale, and what changes when I run Update Memory?”
• “Help me create a focused Run Pack without including unrelated memory.”
• “Diagnose why a saved file is not visible. Ask me first which storage mode is open.”
• “Explain the difference between updating memory, creating a Run Pack, and editing a blueprint.”