claude-code-semantic-memory

Claude Code plugin that gives the agent seamless, Cursor-style semantic memory: a persistent vector index of your repo that the model queries silently during normal conversation. Bundled LogosDB MCP (logosdb-mcp-server), local on-device embeddings by default (no API keys), slash-invoked skills.

Structure follows Anthropic’s example-plugin (README): .claude-plugin/plugin.json, root .mcp.json, and skills/*/SKILL.md (preferred over legacy commands/*.md).

<<<<<<< HEAD

What happens automatically

Once installed and the CLAUDE.md drop-in template is added to your project, the plugin runs silently — the user never has to think about it.

Event	Action
Session start	Incremental re-index of the project directory (honours .gitignore; only changed/new files re-embed). Then silently searches the global namespace for memories relevant to the session context.
Every user prompt	Agent calls logosdb_search silently, surfaces relevant memories from global + code namespaces, and incorporates them into the answer with brief file citations.
After each agent turn	Persists a compact turn record (Q + A + thinking trace if available) to the global namespace for future sessions. Incremental re-index picks up any files the agent just edited.
Session compaction	Stores a handoff note so the next session can pick up context.

All automatic actions are silent — no output is printed to the console.

Memory scope

Controlled by LOGOS_MEMORY_MODE (default: global).

global (default)

Turn records and thinking traces are stored in ~/.claude/.logosdb, visible across all sessions and all projects.

# default — no env var needed

project

Memory is isolated to the current project's .logosdb/ directory. Each repo has its own independent memory.

export LOGOS_MEMORY_MODE=project

Namespaces

Namespace	Purpose	Scope
global	Cross-session Q+A, thinking traces, persistent facts	All projects
code	Source files (auto-indexed with /index .)	Current project
docs	Documentation	Current project
decisions	Architectural decisions, notes	Current project
=======

Install (plugin)

/plugin marketplace add jose-compu/claude-code-semantic-memory
/plugin install semantic-memory

MCP logosdb runs /bin/sh + scripts/logosdb-mcp-wrap.sh (see .claude-plugin/plugin.json, mirrored in .mcp.json). Wrapper sets LOGOSDB_PATH, LOGOSDB_INDEX_ROOT, and cd from CLAUDE_PROJECT_DIR when present (claude-code#42687). claude --debug if tools are missing.

8e0e6d7ae1b6fe734cef2b0c7998799024a41812

How it feels (Cursor-style)

The plugin behaves like Cursor's built-in indexing + semantic search — except it runs fully locally, lives inside Claude Code, and the agent drives it through one MCP server.

user> what is Terminus' agentic philosophy?

agent (silently) → logosdb_search(query="Terminus agentic philosophy", namespace="code", top_k=5)
agent (reply)    → "Terminus-2 is built around three ideas: a single-tool tmux
                    interface, full autonomy (never asks the user during a task),
                    and a clean split between agent logic and Docker environment.
                    See terminus.txt for the full design notes."

How this differs from Cursor's memory:

• Local-first. Embeddings run on-device via Transformers.js (Xenova/all-MiniLM-L6-v2, 384 dims). No API keys, no cloud calls.
• Cross-session. Turn records and thinking traces are stored globally by default — future sessions surface relevant past reasoning automatically.
• Persistent and inspectable. Vectors live on disk under ~/.claude/.logosdb (global mode) or .logosdb/ (project mode). rm -rf to reset.
• Explicit namespaces. global, code, docs, decisions — scope retrieval precisely.
• Quiet by design. All background operations are silent; slash commands enforce one-line outputs.

Layout

claude-code-semantic-memory/
├── .claude-plugin/
│   └── plugin.json          # metadata + inline mcpServers.logosdb
├── scripts/
│   └── logosdb-mcp-wrap.sh  # sets LOGOSDB_PATH from CLAUDE_PROJECT_DIR, runs npx server
├── .mcp.json                # same MCP block as plugin.json (mirror)
├── commands/
│   └── README.md            # note: slash skills live under skills/
├── skills/
│   ├── semantic-memory/     # model-invoked guidance + CLAUDE.md template
│   │   ├── SKILL.md
│   │   └── .claude/commands/   # optional copy → project /index /search /forget
│   ├── index/               # user-invoked → /index
│   ├── search/              # user-invoked → /search
│   ├── forget/              # user-invoked → /forget
│   └── remember/            # user-invoked → /remember (store to global)
└── README.md

Install (user-wide ~/.claude.json) — recommended for stable LOGOSDB_PATH

Store vectors under ~/.claude/.logosdb (one tree for all projects) and register MCP once in your user config. Matches the usual Claude Code pattern: MCP docs (stdio + npx).

1. Merge the mcpServers block from skills/semantic-memory/references/user-claude-json-logosdb.json into ~/.claude.json (same key shape as other servers). It uses "LOGOSDB_PATH": "${HOME}/.claude/.logosdb" so the path is absolute after expansion. If your client does not expand ${HOME}, replace it with an absolute path (e.g. /Users/you/.claude/.logosdb).

2. Only one logosdb server: if you use ~/.claude.json, disable or uninstall this plugin’s MCP (or the whole plugin) so you do not register logosdb twice.

3. CLI (optional): some builds support adding stdio MCP from the shell, e.g. claude mcp add — run claude mcp --help for the exact subcommands on your version.

4. If npx fails or exits oddly: clear the ephemeral install cache, then retry (common with npx + native deps):

   rm -rf ~/.npm/_npx
   npm cache clean --force
   LOGOSDB_PATH="$HOME/.claude/.logosdb" npx -y logosdb-mcp-server

   (Stop with Ctrl+C once it is running.) Then restart Claude Code.

5. Logs: ~/.claude/logs/mcp-server-*.log (names vary by build) for MCP spawn errors.

Project-only DB (per-repo ./.logosdb): use skills/semantic-memory/references/project-mcp-fallback.json in .claude/mcp.json at the repo root instead — still only one active logosdb registration.

Slash commands (skills format)

/index uses logosdb_index_file with incremental: true (new/changed files only; needs logosdb-mcp-server ≥ 0.7.11). With the plugin active, project CLAUDE.md should require the agent to run /index . on every Claude session load before other work (see skills/semantic-memory/SKILL.md — Prerequisites plugin contract, §4c, §7 template). Hooks can enforce this if you need a guarantee beyond model instructions.

All four skills enforce concise output (one-line for /index, /forget, and /remember; header + numbered file/score lines for /search) and tell the agent not to dump the raw MCP JSON or chunk text in its prose answer. Background logosdb_search calls follow the same quiet rule. See skills/semantic-memory/SKILL.md §7b.

Command	Skill
/index	skills/index/SKILL.md
/search	skills/search/SKILL.md
/forget	skills/forget/SKILL.md
/remember	skills/remember/SKILL.md — explicitly store text to global (or --namespace)

CLAUDE.md drop-in template

Paste the block from skills/semantic-memory/references/claude-md-template.md into the project's CLAUDE.md to wire up: mandatory /index . at session start, the slash-command table, namespace conventions, quiet-mode guidance for background searches, and instructions for forcing a re-index when incremental: true reports skipped_files. The same block is reproduced inline in skills/semantic-memory/SKILL.md §7.

Optional project-only prompts (without the plugin): copy skills/semantic-memory/.claude/commands/ into .claude/commands/ (same idea as upstream LogosDB).

Model-invoked guidance

skills/semantic-memory/SKILL.md — routing, CLAUDE.md snippet, troubleshooting.

Local development

cd /path/to/claude-code-semantic-memory
claude --plugin-dir .

Then /mcp or logosdb_list to confirm the server.

License

MIT — see LICENSE.