Cognitive Memory MCP Server

Type: Local MCP Server

Value: Gives agents durable local episodic, semantic, and working-memory primitives through MCP tools.

Current Status

Complete as a local MCP server slice. It provides durable local memory tools over stdio with a file-backed JSON store and deterministic retrieval.

Shipped Local Scope

• MCP tools for write_memory, search_memory, summarize_context, pack_context, list_memory, delete_memory, clear_memory, and memory_stats
• Separate episodic and semantic memory records with tags, importance, session IDs, access counts, and timestamps
• File-backed local JSON store with a configurable path
• Working-memory budget helper for context packing and deterministic summary text
• Input validation at the MCP boundary with JSON-RPC invalid-request and invalid-params errors
• Package bin for launching the MCP server locally

Install And Run

npm install
npm test
npm run mcp

After build, the package exposes:

cognitive-memory-mcp

For MCP client configuration, point the command at the built server:

{
  "mcpServers": {
    "cognitive-memory": {
      "command": "node",
      "args": ["dist/mcp/server.js"],
      "env": {
        "COGNITIVE_MEMORY_STORE_PATH": "./.cognitive-memory/memory.json"
      }
    }
  }
}

Local Storage

By default, the MCP server writes to:

.cognitive-memory/memory.json

Override with either:

COGNITIVE_MEMORY_STORE_PATH=/path/to/memory.json
COGNITIVE_MEMORY_STORE=/path/to/memory.json

The store file is versioned JSON:

{
  "version": 1,
  "records": []
}

SDK Surface

import { createMemoryStore } from '@blair/cognitive-memory-mcp-server';

const store = createMemoryStore({ storePath: './memory.json' });
store.load();

const memory = store.writeMemory({
  type: 'semantic',
  content: 'CertaWorks products should state local versus hosted scope clearly.',
  tags: ['certaworks'],
  importance: 0.8
});

const results = store.searchMemory({
  query: 'hosted scope',
  sessionId: memory.sessionId,
  minScore: 0.01
});

Current Limits

• This is a local product slice, not hosted SaaS.
• There is no public npm publication, live checkout, multi-user auth, team workspace, encrypted remote storage, billing, or hosted retention policy.
• Search is deterministic lexical relevance with recency, tag, and importance weighting; embedding/vector search is future work.
• summarize_context returns deterministic packed-memory summary text, not an LLM-generated synthesis.

Verification

Fresh suite verification on 2026-05-28:

• npm test passed, 27/27 tests across the unit, MCP, persistence, and package contract suite.
• npm run build passes.
• MCP stdio smoke checks cover initialize, write, search, summarize, and stats.