# memos-mcp-server

A small Python MCP server that bridges any MCP-compatible IDE (VS Code, Cursor, Claude Code) to a local [MemOS](https://github.com/MemTensor/MemOS) instance, so notes you take in your editor land in the same knowledge base your AI agents read from.

Designed for the Animus Systems / Paperclip stack, where MemOS is already running in Docker and serving as the shared knowledge layer for ~50 Paperclip agents. Until now, knowledge written in human IDE sessions and knowledge written by agents lived in different worlds. This server closes that loop with one config line.

## Why

Sequence of events from a real Paperclip session:

1. You tell Claude/Copilot in VS Code: *"the accounts rename routine uses spaces around all dashes and 3-letter currency codes"*
2. That fact is captured nowhere persistent — when the session ends, it's gone
3. Two days later your bookkeeping agent runs the routine, doesn't know the convention, gets it wrong, and you have to type the same explanation into a Paperclip issue description

With this MCP server, step 1 stores the fact into MemOS via `memos_remember`. The Paperclip agent-memory plugin's pre-run hook auto-injects the same MemOS scope into every agent run. The bookkeeping agent picks up the convention on its next heartbeat, no plugin changes required.

## Tools

| Tool | What it does |
|---|---|
| `memos_remember(content, category, project, tags)` | Store a memory. Auto-redacts credentials before sending. |
| `memos_search(query, top_k, only_human)` | Search MemOS, return ranked results with metadata. |
| `memos_recent(hours, source)` | Recent memories (default last 24 h), optional source filter. |

A startup health check pings MemOS once and logs the result; tool errors are returned cleanly when MemOS is unreachable rather than crashing the server.

## How it integrates with Paperclip

The default config writes to MemOS scope `user_id = kb-{companyId}` — the **same scope** the Paperclip agent-memory plugin uses for its KB entries. This is the scope the OpenRouter adapter's pre-run hook queries when it builds the *"## RELEVANT CONTEXT FROM PREVIOUS RUNS"* block injected into every agent run.

So a memory you write from VS Code is, with zero plugin changes, automatically available to every Paperclip agent's next run. Bidirectional human ↔ agent memory.

If you don't want this — e.g. you want personal notes that Paperclip agents can't see — change `MEMOS_USER_ID` in the env block to something like `seth-personal`.

## Install (macOS)

```bash
git clone https://github.com/mchosc/memos-mcp-server.git ~/Documents/GitHub/animusystems/memos-mcp-server
cd ~/Documents/GitHub/animusystems/memos-mcp-server
bash install.sh
```

Then open `~/Library/Application Support/Code/User/mcp.json` and add the entry from `vscode-mcp.snippet.json` under the `servers` object. Reload VS Code (`Cmd+Shift+P → "Developer: Reload Window"`).

The server will auto-start the next time you open the Chat panel and use any MCP tool. Verify it's connected by asking: *"What MCP tools do you have?"*

## Configuration

All config is read from environment variables, which you set in the VS Code mcp.json `env` block:

| Env var | Default | Purpose |
|---|---|---|
| `MEMOS_URL` | `http://localhost:8000` | MemOS HTTP base URL |
| `MEMOS_CUBE_ID` | Animus Group UUID | Paperclip companyId — used as MemOS cube |
| `MEMOS_USER_ID` | `kb-${MEMOS_CUBE_ID}` | MemOS user_id scope (default: shared with agent KB) |
| `MEMOS_AUTHOR` | `human` | Author tag stamped on every entry |
| `MEMOS_ORIGIN` | `vscode` | Origin tag (e.g. `vscode`, `cursor`, `claude-code`) |
| `MEMOS_TIMEOUT_SEC` | `15` | HTTP request timeout |

## A note on MemOS consolidation

MemOS stores raw entries via `/product/add` but its internal pipeline runs an LLM (Mistral Small 3.2 in the Animus deployment) to consolidate raw entries into "evolving knowledge objects" — paraphrased, deduplicated versions of related memories. Searches return **both** the raw entries and the consolidated ones, and the consolidated ones often outrank the raw because they're cleaner.

Practical implication: the inline `[source: human]` / `[author: seth]` / `[category: note]` tags this MCP server adds to your content **may not survive consolidation**. The semantic content is preserved (your decisions, conventions, and notes still appear in search results), but the structured metadata block can be paraphrased away.

When that happens, search results display `(consolidated)` instead of the raw tag values. The `only_human=True` filter in `memos_search` only works for entries that still carry the raw tags — useful when you've just stored something, less useful weeks later when consolidation has run.

If you want guaranteed verbatim recall of personal notes, set `MEMOS_USER_ID` to a separate scope (e.g. `seth-personal-raw`) and skip the shared KB scope. That trade-off costs you the bidirectional human↔agent visibility.

## Sanitizer

`memos_remember` runs the content through a regex sanitizer (`sanitizer.py`) before storing. Patterns currently covered:

- Credit card numbers (Visa / MC / Amex / Discover)
- IBAN
- US SSN
- PEM private keys
- AWS access keys / secret keys
- Generic API keys (`sk-`, `sk-or-v1-`, `sk-ant-`, GitHub PATs `ghp_*`/`gho_*`, GitLab `glpat-`, Slack `xox[bps]-`)
- Bearer tokens
- Connection strings with embedded creds (postgres / mysql / mongodb / redis / amqp / smtp)
- JWT tokens
- Password / token assignments (`password=...`, `api_key: ...`, etc.)

These are ported from [`paperclip-plugin-agent-memory/src/worker/sanitizer.ts`](https://github.com/mchosc/paperclip-plugin-agent-memory/blob/master/src/worker/sanitizer.ts). If new patterns get added there, port them here too — the README documents what's covered.

When something is redacted, the tool's response includes a note like *"sanitized: 1x api_key"* so you know it happened.

## Usage examples

From any MCP client connected to this server, just ask:

> *"Remember that we set autoDecompose to false on the Animus Group task-triage plugin to stop routine fires from being decomposed into stuck-blocked subtasks."*

The model calls `memos_remember(content="...", category="decision", project="paperclip", tags=["task-triage", "routines"])`. Done.

A week later from a fresh session:

> *"Why did we disable autoDecompose on task-triage?"*

The model calls `memos_search(query="autoDecompose task-triage")` and gets the original decision back, verbatim, with the date and reason.

## Troubleshooting

**`MemOS unreachable at http://localhost:8000`**
Docker stack isn't running. `cd ~/Documents/paperclip-data && ./restart.sh` or `docker compose up -d memos`.

**Tools don't appear in VS Code chat**
1. Check the mcp.json was saved with valid JSON (`jq < ~/Library/Application\ Support/Code/User/mcp.json`)
2. Reload VS Code (`Cmd+Shift+P → "Developer: Reload Window"`)
3. Open the Chat panel → MCP servers panel; you should see `memos` listed
4. If it shows as failed, run the server manually to see the error: `/Users/seth/Documents/GitHub/animusystems/memos-mcp-server/.venv/bin/python3 /Users/seth/Documents/GitHub/animusystems/memos-mcp-server/server.py` (it will block on stdin — that's fine, you just want to see startup logs on stderr)

**Memories aren't showing up in agent runs**
The shared `kb-{companyId}` scope is only auto-injected by the Paperclip agent-memory plugin's pre-run hook. Check:
1. The plugin is loaded: `docker logs paperclip-data-server-1 2>&1 | grep agent-memory`
2. Your memory has the right `cube_id` (matches the agent's companyId)
3. The relevance ranking — MemOS is semantic, so unrelated queries won't surface your note. Try a `memos_search` with a similar query first to confirm it's findable.

**I want personal notes that agents can't see**
Change `MEMOS_USER_ID` in your mcp.json env block from `kb-...` to something like `seth-personal`. The server will use that scope instead, and agent runs (which still query `kb-...`) won't see those entries.

## License

MIT