The Problem

Developers using LLM‑driven coding agents lose context once a session ends. Agents must repeatedly re‑learn a project's architecture, decisions, and terminology, which wastes time and leads to inconsistent outputs.

What This Does

MegaMemory implements a local MCP (Model Context Protocol) server that persists a knowledge graph in a per‑project SQLite file (.megamemory/knowledge.db). The agent writes natural‑language concepts via create_concept / update_concept and retrieves them with understand or get_concept.

Key implementation files:

  • src/index.ts – launches the MCP server (startMcpServer).
  • src/db.ts – all SQLite interactions (runInTransaction, migrate, etc.).
  • src/web.ts – static web UI served from the web/ folder.
  • src/install.ts – CLI installer that writes config files and the embedding model.

The repository is TypeScript‑first (25 TS files) with a small React UI under src/web.ts and supporting scripts in scripts/.

How It Is Wired

Execution begins at src/index.ts:147 (startMcpServer). The server creates a MegaMemoryServer instance that:

  1. Calls src/db.ts to open or create .megamemory/knowledge.db. The DB module is the central hub – 14 other modules import it, and it defines 44 functions (e.g., runInTransaction, runWithRetry).
  2. Registers MCP RPC handlers (understand, create_concept, get_concept, etc.) that invoke utility functions in src/tools.ts and src/embeddings.ts.
  3. For web access, src/web.ts resolves index.html from web/ and serves JSON endpoints that again delegate to src/db.ts.

The internal call graph shows the most‑used utilities: success (11 callers), info (8), errorBold (7), and the DB helper runInTransaction (6). These functions have the widest blast radius; changes here affect most request paths. No circular imports were detected, so dependency changes are predictable.

External effects:

  • Filesystem – src/install.ts reads/writes config files (e.g., fs.readFileSync, fs.writeFileSync).
  • SQLite – all CRUD operations in src/db.ts read/write the knowledge database.

The test harness (src/__tests__/helpers/db-worker.ts) demonstrates the same DB path handling, confirming that the core persistence path is exercised in both production and test code.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/MegaMemory
cd MegaMemory

# Install globally (npm is the package manager)
npm install -g megamemory

# Run the interactive installer (writes config files and downloads the embedding model)
megamemory install

The installer writes a .megamemory/knowledge.db file in the current project directory. To start the MCP server manually:

# Starts the local MCP server on the default port
megamemory

Clients connect by adding the following snippet to their MCP configuration (e.g., ~/.config/opencode/opencode.json):

{
  "megamemory": {
    "type": "local",
    "command": ["megamemory"],
    "enabled": true
  }
}

The optional web UI is reachable at http://localhost:<port>/ and is served by src/web.ts.

Real‑World Use

A CI pipeline could invoke megamemory understand "authentication flow" before a code‑generation step, allowing the LLM to retrieve the stored concept of the project's auth architecture. After the generation, megamemory create_concept records any new decisions, keeping the graph up‑to‑date without manual documentation.

Code Health & Issues

  • Medium – Enable Dependabot – No update bot configured; add .github/dependabot.yml.
  • Medium – Dependency‑vulnerability scan – CI lacks a scan step; integrate dependency-review-action or osv-scanner.
  • Medium – Persist‑credentials false – Checkout keeps the token; set persist-credentials: false in publish.yml.
  • Low – Job timeouts – Workflow jobs have no timeout-minutes; add a reasonable bound.

Measured findings:

  • High – Duplicated test code – 34 repeated 6‑line blocks across 10 test files; extract shared helpers.
  • Medium – Oversized files – src/db.ts, src/__tests__/db.test.ts, src/install.ts each exceed 800 lines; consider splitting by responsibility.
  • Medium – Hub module – src/db.ts is imported by 14 modules; keep its API stable and move volatile logic elsewhere.
  • Medium – Empty catch blocks – scripts/stress-test*.js swallow errors; add logging or rethrow.

No critical structural issues were found; the test suite and CI are present, and the license file is included.

The Bottom Line

MegaMemory delivers a lightweight, persistent knowledge graph that integrates cleanly with LLM‑based coding agents via a local MCP server. The core DB module is well‑encapsulated but large, and the codebase would benefit from modular refactoring and standard CI hardening. It is suitable for teams that need a simple, self‑hosted context store without heavy static analysis overhead.