Memory & Obsidian

Understand OFM's persistent project memory, review what your agents learn, and connect a live Obsidian vault through MCP.

Open Free Max has a memory model that is deliberately different from a chat history and from an AI cloud memory feature. It keeps durable project knowledge on your machine, lets you review what should become a fact, and can give an agent direct access to an Obsidian vault without copying that vault into OFM.

Three kinds of context

These three layers work together, but they are not the same thing:

The important boundary is this: resuming a session restores a conversation; saving a fact makes knowledge available beyond that conversation; connecting Obsidian gives the agent a tool for your existing vault. OFM does not silently merge the three stores.

OFM project memory

Every project can have a private knowledge layer that behaves like a small, local, inspectable knowledge base. It is designed for information that should survive a session and remain useful after you switch providers:

• architectural decisions and their rationale;
• project conventions, commands and constraints;
• durable facts about the codebase or product;
• links between related concepts, notes and decisions;
• the source and provenance of each item, so you can understand why it exists.

OFM can read the local history produced by supported agent CLIs and propose durable knowledge. It does not turn every line of every conversation into a permanent memory. The useful distinction is between a transcript, which is evidence, and an approved fact, which is reusable context.

The memory workflow

1. Work normally. Run Claude Code, Codex or another supported CLI in an OFM project. The provider keeps the transcript in its own local store.
2. Search when you need context. Open the project’s Memory view and use Search to find previous decisions, facts and notes. Search is semantic, so it can find relevant ideas even when your query does not repeat the original wording.
3. Review proposals. Open To review to see knowledge distilled from project activity. Each proposal remains readable and traceable before it becomes trusted.
4. Curate what sticks. Approve a proposal, edit it first, or reject it. Nothing becomes trusted project knowledge merely because it appeared in a conversation.
5. Use it in another session. Approved knowledge can be made available to the next agent, the next provider or the next day of work without pasting the same briefing again.

How memory reaches an agent

OFM adapts the delivery to the CLI:

• Claude Code can query the local memvault MCP server when it needs relevant knowledge.
• Other supported CLIs receive the approved facts in a tagged section of the project’s guidance file, such as CLAUDE.md, AGENTS.md or GEMINI.md, when that integration is available.
• The tagged section is idempotent: OFM updates its own block and does not rewrite the rest of your instructions.

This means memory is available on demand or as explicit project guidance, rather than being hidden in an opaque prompt assembled by a hosted service.

What should become memory?

Good candidates are stable facts that will still matter next week: “the API uses UTC”, “this module must remain dependency-free”, “the migration was rejected because of backward compatibility”, or “run this test suite before changing the parser”.

Keep temporary thoughts, one-off debugging output and secrets out of durable memory. Review proposals as if you were maintaining a project handbook: keep the short version, include the reason when it matters, and reject anything that is obsolete or too sensitive.

Local, inspectable and private

The native memory database and search index stay on your computer. OFM does not upload the knowledge base or collect your LLM exchanges. See Data & file locations for the platform-specific config directory and the files involved.

Connect a live Obsidian vault

If you already use Obsidian, you do not need to migrate your notes into OFM. OFM can connect the agent to the vault that is open in the Obsidian desktop application. The agent receives an obsidian MCP server and can use it to work with the live vault while you keep Obsidian as the place where your notes are organized.

The connection is provided by the Local REST API community plugin for Obsidian. Its built-in MCP server uses Streamable HTTP and bearer-token authentication. Depending on the permissions you grant through the agent CLI, the available operations include:

• search notes and metadata;
• list files and inspect the active note;
• read an existing note;
• create a new note;
• update a heading, block reference or frontmatter field;
• open a note in the Obsidian window.

OFM connects to the loopback interface on your own computer. It does not need your vault path, and it does not mirror the vault into the native OFM memory database.

Set up the Obsidian connection

Before opening the OFM settings, make sure Obsidian is installed, your vault is open, and you are working in the vault you want the agent to access.

1. Install and enable Local REST API

1. In Obsidian, open Settings.
2. Select Community plugins and choose Browse.
3. Search for Local REST API, install it, then enable it.
4. Open the Local REST API plugin settings.

2. Enable the local HTTP endpoint

In the plugin settings, enable the plain HTTP server. Note the port shown by the plugin and copy the generated API key. The default HTTP port is commonly 27123, but use the value shown in your installation if you changed it.

The endpoint must remain local. Use the loopback host 127.0.0.1; do not expose the server on your LAN or forward the port to the internet. The API key grants access to the vault, so treat it like a password and never paste it into a prompt, issue or public configuration file.

3. Add it to the OFM project

1. Open the project that should use this vault in OFM.
2. Open Memory and select the Obsidian vault tab.
3. Enable the Obsidian connection.
4. Enter the HTTP port from the plugin settings and paste the API key.
5. Select Test connection and wait for the success result before starting an agent.

OFM keeps the connection configuration local, validates that the host is loopback, and passes the bearer token to the agent integration through the process environment rather than exposing it on a command line.

4. Start a session

Start a new Claude Code or Codex session for the project after the connection test succeeds. OFM declares the obsidian MCP server automatically for that session. If a session was already running while you changed the setting, stop it and start a new one so it receives the updated configuration.

You can then ask the agent for a specific operation, for example:

Search the vault for the notes about the authentication decision, then summarize the two constraints that apply to this project.

Read Projects/OpenFreeMax/architecture.md, compare it with the current code, and tell me which decision is now outdated. Do not edit the note.

Create a note in Projects/OpenFreeMax/decisions/ recording this approved database choice, including today’s date and a link to the relevant source file.

Be explicit about whether you want the agent to read, propose a change or write a change. The agent still operates through the normal CLI permission and confirmation flow; a connected vault does not make every write automatic.

OFM memory and Obsidian are complementary

Use the two systems for different jobs:

OFM does not index, mirror or import the external vault into its native project memory. It also does not export native facts into Obsidian behind your back. If the same concept belongs in both systems, make the relationship explicit yourself, for example by linking an OFM project fact to the Obsidian note that contains the canonical decision.

This separation prevents duplicate or conflicting copies while still letting one agent use both sources in the same session: OFM memory for durable project context, and Obsidian for the live knowledge graph you already maintain.

Troubleshooting the connection

Test connection fails

• Keep Obsidian open with the target vault loaded.
• Confirm that Local REST API is enabled.
• Confirm that its HTTP server is enabled and that the port in OFM matches the plugin port.
• Generate a new API key in the plugin settings and paste it again if the key was rotated.
• Check that the endpoint is bound to 127.0.0.1 and not a remote hostname.

The agent cannot see obsidian

Save the connection settings, stop the current session and start a new one. MCP servers are declared when the CLI process starts, so an already-running session may not see a configuration change.

Reads work but an update is refused

The connection can be healthy while the agent CLI still asks for confirmation or refuses a write. Review the exact path and requested operation, approve it deliberately, and check the resulting note in Obsidian. Do not broaden permissions just to bypass a single confirmation.

The wrong vault is being used

The Local REST API belongs to the vault currently open in that Obsidian instance. Close or switch to the intended vault, then run Test connection again in the matching OFM project.

I want to disconnect Obsidian

Disable the connection in Memory → Obsidian vault and start a new agent session. OFM will stop declaring the obsidian MCP server for new sessions; your native OFM project memory remains untouched.