@agentsoft/agent-memory

Obsidian-backed structured note MCP server for coding agents.

Pairs with @agentsoft/agent-knowledge — where agent-knowledge does semantic search over ingested deliverables, agent-memory handles structured, human-editable notes in an Obsidian vault (registries, session memory, audit gates, project history).

Install

npm install -g @agentsoft/agent-memory

Prerequisites:

• Obsidian desktop app v1.12+ installed, running, and with "Command line interface" enabled under Settings → General
• The obsidian CLI binary on your PATH, or set AGENT_MEMORY_OBSIDIAN_PATH to its absolute path
• Node 18+

Run the MCP server

agent-memory

The server speaks stdio and registers 11 tools.

Tools

Read-only:

• memory_read — fetch a note's full content
• memory_list — list every note path in a vault
• memory_search — full-text search a vault
• memory_tag — list notes tagged with a given tag
• memory_backlinks — list notes that link to a given note

Write:

• memory_create — create a new note
• memory_append — append to an existing note
• memory_delete — trash or permanently delete a note
• memory_move — move/rename a note (preserves wikilinks)
• memory_property_set — set a frontmatter property
• memory_property_remove — remove a frontmatter property

Every tool takes a required vault parameter — the server is stateless.

Notes on memory_property_set

All values are written as YAML strings. Callers wanting typed frontmatter (numbers, booleans, lists, dates) should manipulate the note body via memory_create / memory_append with a complete frontmatter block instead. A dedicated memory_property_get tool is tracked for v0.2 — today, agents should use memory_read and parse the frontmatter themselves.

Configuring MCP clients

Claude Code

claude mcp add agent-memory --server agent-memory

Manual config (Gemini, Codex, etc.)

{
  "mcpServers": {
    "agent-memory": {
      "command": "agent-memory",
      "env": {
        "AGENT_MEMORY_OBSIDIAN_PATH": "/Applications/Obsidian.app/Contents/MacOS/Obsidian"
      }
    }
  }
}

Per-agent permissions

The MCP has no server-side ACL. Restrict each agent's allowed tools via its own frontmatter tools: list. Example — a read-only agent:

tools: mcp__agent-memory__memory_read, mcp__agent-memory__memory_search, mcp__agent-memory__memory_list, mcp__agent-memory__memory_tag, mcp__agent-memory__memory_backlinks

A full-write agent:

tools: mcp__agent-memory__memory_read, mcp__agent-memory__memory_create, mcp__agent-memory__memory_append, mcp__agent-memory__memory_delete, mcp__agent-memory__memory_move, mcp__agent-memory__memory_search, mcp__agent-memory__memory_list, mcp__agent-memory__memory_tag, mcp__agent-memory__memory_backlinks, mcp__agent-memory__memory_property_set, mcp__agent-memory__memory_property_remove

Verifying (manual)

With Obsidian running and a vault named Scratch:

# Via an MCP client, call:
# memory_create(vault="Scratch", file="test-note", content="hello")
# memory_read(vault="Scratch", file="test-note")
# memory_delete(vault="Scratch", file="test-note")

Automated tests mock the subprocess and never touch a real vault.

Library API

import { createMemory, createObsidianCliAdapter } from '@agentsoft/agent-memory'

const noteStore = createObsidianCliAdapter({ binaryPath: 'obsidian' })
const memory = createMemory({ noteStore })

const content = await memory.read('MyVault', 'path/to/note')

Architecture

Thin hexagonal wrapper:

• NoteStore port (11 methods matching the tool surface)
• obsidian-cli adapter spawns the obsidian binary
• Memory factory delegates to the NoteStore
• MCP server registers 11 tools, each handler calls one memory.*() method

License

MIT