Cognitive Memory

License NPM Version CI TypeScript Testing PRs Welcome Support me on Ko-fi

Building the cognitive nervous system for AI agents.

A high-performance, local-first Model Context Protocol (MCP) server that provides AI agents with persistent, human-readable cognitive memory.

Unlike cloud-based memory solutions (Letta, Graphiti), Cognitive Memory runs entirely on your local machine using SQLite and local LLM embeddings. This ensures zero latency, zero API costs, and absolute data privacy.

TL;DR: The Web UI Dashboard (coming soon) is a quick way to visually explore the memory graph. The CLI + MCP Server is how you make your AI agent reliable — it gives Antigravity, Cursor, and Claude a deep cognitive memory layer so they stop forgetting past context across sessions.

---

Two Ways to Use Cognitive Memory

	CLI + MCP Server	Web UI Dashboard (WIP)
What	Connect AI agents to local SQLite vector memory via MCP	Visual 3D graph explorer of the agent's brain
For	Daily development with Antigravity, Cursor, Claude Code	Quick exploration, human-agent memory debugging
Scale	Unlimited local memory scaling via better-sqlite3	Visualizes clusters and memory relationships
Storage	Native SQLite + sqlite-vec (fast, persistent)	Directly reads the local SQLite database
Privacy	Everything local, no network (uses local Ollama)	Everything local, runs on localhost

---

🌟 Why We Are Unique: Human-Agent Cognitive Symmetry

Most AI memory platforms (like Graphiti, Letta, Cognee) lock the AI's "brain" inside opaque databases (Neo4j, ChromaDB, Pickles). If the AI remembers something incorrectly, it becomes a "black box" that is difficult for a human to debug or edit.

Cognitive Memory pioneers Bi-directional Human-Agent Symmetry: We bridge the gap between an AI's Long-Term Memory and a human's Second Brain.

• Obsidian Sync: The AI's memory synchronizes natively with interconnected Markdown files in an Obsidian vault.
• Read & Edit: Open Obsidian (or the Web Dashboard) to visually read and edit what the agent is thinking.
• Write: Write your own notes, and the agent natively understands them via Vector+Graph search.

✨ Features

• Semantic LTM: Stores and retrieves long-term declarative memories using Cosine Similarity vector search.
• Local Vectors & Embeddings: Uses sqlite-vec and integrates directly with Ollama (qwen3-embedding:8b) to generate 4096-dimensional embeddings locally without hitting external APIs.
• Hybrid Graph Relations: Connects memories together to form an explicit, interconnected knowledge graph.
• Code Intelligence: Integrates GitNexus via a Git post-commit hook to asynchronously update the AST knowledge graph for deep codebase intelligence.

🚀 Installation & Setup

We recommend a simple 2-step process to get Cognitive Memory fully integrated into your workflow.

Prerequisites

• Node.js (v24+ recommended)
• pnpm (v9+)
• Ollama running locally on port 11434 with the following models pulled:

  ollama pull qwen3-embedding:8b
  ollama pull llama3.2
  

Step 1: Global Editor Setup (The "Hands")

To give your AI Assistant access to the database tools, run the global setup script. This auto-detects your installed AI Editors (Antigravity, Cursor, Claude Desktop, Claude Code, Copilot, Windsurf, OpenCode) and injects the MCP server directly into their global JSON/TOML configuration files:

npx -y @cemised/cognitive-memory setup

Step 2: Local Project Initialization (The "Brain")

Having the tools is not enough; the AI needs to know when and how to use them autonomously. Navigate to your project folder and run the initialization script to inject the AGENTS.md memory forcing-function checklist and the auto-capture SKILL.md:

cd my-project
npx -y @cemised/cognitive-memory init

Note: You only need to run Step 1 once per machine. You should run Step 2 for every new codebase you want your AI to memorize.

💻 Manual MCP Configuration (Optional)

If you prefer not to use the setup script, you can manually add the following to your client's MCP configuration file (e.g. mcp_config.json):

{
  "mcpServers": {
    "cognitive-memory": {
      "command": "npx",
      "args": [
        "-y",
        "@cemised/cognitive-memory"
      ]
    }
  }
}

Build from Source (For Developers)

If you want to modify the source code or if your environment requires compiling native C++ bindings for SQLite manually:

git clone <repository-url>
cd cognitive-memory
pnpm install
pnpm rebuild  # Crucial for native SQLite C++ bindings
pnpm run build

Then configure your MCP client to point to the local build instead:

{
  "mcpServers": {
    "cognitive-memory": {
      "command": "node",
      "args": [
        "/absolute/path/to/cognitive-memory/dist/index.js"
      ]
    }
  }
}

Exposed AI Tools

Once connected, the server exposes 8 powerful tools to your AI agent:

• memory_search: Perform optimized vector similarity cosine searches on stored memories.
• memory_store: Encrypt/Hash, vectorize, and persist a semantic memory into a local SQLite database.
• memory_relate: Establish a graph relationship between two memory nodes.
• memory_sync: Perform a bidirectional synchronization between local Obsidian Markdown files and the SQLite database.
• memory_export: Export active database memories into Markdown notes for Obsidian integration.
• memory_consolidate: Perform time decay and semantic LLM merging/deduplication on active memories using Ollama.
• memory_delete: Delete a specific semantic memory record by its identifier.
• memory_clear_all: NUCLEAR OPTION: Completely wipe all memories, vectors, and graph edges from the database. Cannot be undone.

🏗️ Architecture

The project adheres to a clean modular architecture:

• src/db.ts: Manages the SQLite connection, schema, and vector extensions.
• src/ollama.ts: Lightweight native fetch wrapper for the Ollama API.
• src/cache.ts: Caches embeddings to avoid recalculating identical strings.
• src/tools/: Contains the business logic for the MCP endpoints.

🤝 Contributing & Community

We welcome community contributions, from bug fixes to new features!

• Please read our Contributing Guidelines to get started.
• Review our Security Policy for vulnerability reporting.

📄 License

This project is licensed under the Apache 2.0 License. This provides strong patent protection and makes the project safe for enterprise adoption.

---

Author / Creator:
Eduards Čemis

💖 Support the Project

If you find this project helpful and want to support its continued development, consider buying me a coffee! ☕

ko-fi