AnchorMem

Local-first MCP memory server MVP built with TypeScript, SQLite, and stdio.

What It Does

• Stores persistent memories in a local SQLite database.
• Exposes write_memory, read_memory, forget_memory, and export_memory as MCP tools.
• Supports keyword retrieval by default.
• Supports optional semantic indexing and candidate extraction through an OpenAI-compatible API.
• Tracks append-only memory events and provenance links.

Run It

Requirements:

• Node 20+
• npm

Install dependencies:

npm install

Start the MCP server:

npm run dev

Start the HTTP MCP server:

npm run dev:http

Build and run the compiled server:

npm run build
npm start
npm run start:http

Environment Variables

• MEMORY_DB_PATH Default: ./.anchormem/memory.db
• REMOTE_INFERENCE_MODE Allowed: off, opt-in, always Default: off
• OPENAI_COMPAT_BASE_URL Example: https://api.openai.com/v1
• OPENAI_COMPAT_API_KEY
• OPENAI_COMPAT_EMBEDDING_MODEL
• OPENAI_COMPAT_EXTRACTION_MODEL
• OPENAI_COMPAT_TIMEOUT_MS Default: 15000
• ANCHORMEM_HTTP_HOST Default: 127.0.0.1
• ANCHORMEM_HTTP_PORT Default: 3000
• ANCHORMEM_HTTP_MODE Allowed: stateless, stateful, both Default: both

Remote inference only runs when both conditions are true:

• REMOTE_INFERENCE_MODE is opt-in or always
• the MCP request includes allowExternalModel: true

Sensitive content detection warns on:

• email-like strings
• phone-like strings
• API key-like strings
• SSN-like strings

If sensitive content is detected and the request did not explicitly opt into external inference, the server will not send that text to an external model.

Real Provider Setup

Example environment for an OpenAI-compatible endpoint:

export REMOTE_INFERENCE_MODE=opt-in
export OPENAI_COMPAT_BASE_URL=https://api.openai.com/v1
export OPENAI_COMPAT_API_KEY=your_api_key
export OPENAI_COMPAT_EMBEDDING_MODEL=text-embedding-3-small
export OPENAI_COMPAT_EXTRACTION_MODEL=gpt-4o-mini

Automated tests keep using stub providers by default. Real API calls are only exercised through manual smoke runs.

MCP Client Example

Example stdio config:

{
  "mcpServers": {
    "AnchorMem": {
      "command": "node",
      "args": ["--import", "tsx", "src/server.ts"],
      "cwd": "/Users/rikxiao/source/personal_mem_os",
      "env": {
        "MEMORY_DB_PATH": "/Users/rikxiao/source/personal_mem_os/.anchormem/memory.db",
        "REMOTE_INFERENCE_MODE": "off"
      }
    }
  }
}

Manual Smoke

Stdio smoke with real credentials:

npm run smoke:provider -- --transport=stdio

HTTP smoke with real credentials:

npm run dev:http
npm run smoke:provider -- --transport=http --url=http://127.0.0.1:3000/mcp

The smoke flow:

• writes a memory with allowExternalModel: true
• requests extraction candidates
• performs a semantic read
• fails if vector indexing or semantic retrieval did not occur

HTTP Transport

See /Users/rikxiao/source/personal_mem_os/docs/http-transport.md for route details and stateful/stateless behavior.

Sync Design

See /Users/rikxiao/source/personal_mem_os/docs/sync-architecture.md for the next-phase sync architecture and conflict rules.

Data Layout

The database includes:

• memories
• memory_links
• memory_events
• memory_embeddings
• memory_fts

The data file defaults to /.anchormem/memory.db relative to the current working directory when the server starts.

Scripts

• npm run dev
• npm run dev:http
• npm run build
• npm run start
• npm run start:http
• npm run smoke:provider
• npm run test
• npm run typecheck

Current Boundaries

This MVP does not include:

• multi-device sync
• HTTP transport
• UI
• SQLCipher
• cloud storage
• CRDT conflict resolution
• automatic background summarization