🏛️ Manthan (@manthan/mcp-server)

Commercial-Grade, Git-Native, Deterministic Memory Engine for AI Agents via Model Context Protocol (MCP)

Unlike probabilistic vector-only memory layers that suffer from black-box semantic drift and silent hallucinations, Manthan treats agent memory as version-controlled state ("Memory-as-Code").

• Git is the Single Source of Truth: Every state update, architectural decision, and session handoff is an atomic Git commit with full author-agent and observability trace metadata.

• Embedded SQLite FTS5 Sidecar Index: Uses Node's built-in node:sqlite (DatabaseSync with BM25 ranking) for sub-5ms deterministic lexical retrieval with zero native C++ compilation dependencies on Windows, Linux, and macOS.

• Git Commit SHA Provenance: Every memory recall operation returns cryptographic commit SHA provenance, providing reproducible time-travel and compliance auditing.

🏗️ Architecture & Multi-Scope Memory

Manthan is completely self-contained and operates out-of-the-box in any repository via a declarative .manthan.yaml manifest:

workspace/
├── .manthan.yaml               # Declarative engine configuration
└── .manthan/
    ├── index.db                # Ephemeral SQLite FTS5 BM25 search sidecar (gitignored)
    └── memory/
        ├── working/            # Active mutable memory (Read/Write)
        │   └── backend/
        │       └── mem_01j9x8.md
        └── constitution/       # Architectural guardrails & ADRs (Read-only)
            └── core/
                └── ADR-001.md

1. Active Memory Store (working Layer — Default)

• Stores live project state, episodic session decisions, task handoffs, and evolving specifications as structured Markdown files with strict YAML frontmatter.

• Access Policy: Read/Write via MCP tools. Every mutation validates against a strict Zod schema and generates an atomic Git commit with metadata (author_agent, trace_id, supersedes).

2. Constitutional Memory (constitution Layer — Guardrail Tier)

• Stores non-negotiable architectural rules, ADRs, and project conventions inside .manthan/memory/constitution/.

• Access Policy: Read-only during standard agent task execution so models cannot accidentally overwrite or drift core project laws. Always prioritized in recall_memory responses. Agents propose additions using propose_constitution_rule (staged as draft for human review).

Related MCP server: openmemkit

📋 Standardized Memory Artifact Schema

Every memory artifact is stored as a standard .md file with strict YAML frontmatter:

---
id: "mem_01j9x8k2m"
title: "API Idempotency Key Header Standard"
layer: "working" # "working" | "constitution"
namespace: "backend/payments" # Logical topic or directory slug
status: "active" # "active" | "superseded" | "draft" | "archived"
author_agent: "claude-code"
trace_id: "tr_98234792"
supersedes: null # Optional ID of previous memory artifact
tags: ["idempotency", "api", "payments"]
updated_at: "2026-11-09T10:00:00.000Z"
---

## Context & Decision
All payment mutation endpoints must accept and validate a unique `Idempotency-Key` header.

🛠️ MCP Tools Specification

Manthan exposes 5 deterministic tools to any MCP-compliant client:

⚙️ Declarative Configuration (.manthan.yaml)

version: "1.0"
project: "my-project"

storage:
  root_dir: ".manthan/memory"
  working_dir: ".manthan/memory/working"
  constitution_dir: ".manthan/memory/constitution"
  index_db_path: ".manthan/index.db"

git:
  auto_commit: true
  branch_strategy: "direct" # "direct" | "session-branch"
  commit_prefix: "chore(manthan):"

governance:
  prioritize_constitution_on_recall: true
  allow_direct_constitution_writes: false

🚀 Quickstart

1. Initialize Manthan in your repository

npx @manthan/mcp-server init

This automatically:

• Creates .manthan.yaml with default settings.

• Creates directory structures for working and constitution memories.

• Adds .manthan/index.db* to .gitignore.

• Initializes Git (if not already initialized).

• Seeds initial constitutional rules (ADR-001) and working memories.

• Builds the local SQLite FTS5 search index.

2. Inspect status

npx @manthan/mcp-server status

🔌 Client Integration

1. Claude Desktop & Claude Code

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "manthan": {
      "command": "npx",
      "args": ["-y", "@manthan/mcp-server", "serve"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "manthan": {
      "command": "node",
      "args": ["<your-path>/manthan-mcp/dist/index.js", "serve"]
    }
  }
}

2. Cursor

In .cursor/mcp.json (or Cursor Settings > Features > MCP):

{
  "mcpServers": {
    "manthan": {
      "command": "npx",
      "args": ["-y", "@manthan/mcp-server", "serve"]
    }
  }
}

3. Google Antigravity

Add to your Antigravity MCP configuration (~/.gemini/antigravity/mcp/manthan.json or config.json):

{
  "name": "manthan",
  "command": "npx",
  "args": ["-y", "@manthan/mcp-server", "serve"]
}

💻 CLI Commands Reference

• manthan init [--dir <path>]: Initialize memory storage and seed artifacts.

• manthan serve [--dir <path>]: Start the MCP server over stdio.

• manthan status [--dir <path>]: View memory counts, Git HEAD, and index health.

• manthan reindex [--dir <path>]: Force a complete rebuild of the SQLite FTS5 index.

🧪 Testing

Run the automated end-to-end integration test suite:

npm test

The test verifies:

1. Workspace initialization and Git repository detection.

2. Atomic commit_memory execution and Git SHA stamping.

3. Sub-5ms BM25 lexical recall with recall_memory.

4. State supersession (marking v1 as superseded, creating v2 as active, excluding superseded items from recall).

5. Constitutional rule proposal and staging with status: draft.

6. Audit lineage retrieval via Git commit logs.

7. Full FTS5 sidecar index rebuilding and HEAD SHA synchronization.

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details on our code of conduct, development setup, architecture guidelines, and pull request submission process.

💖 Sponsorship & Support

If Manthan helps eliminate hallucination and state drift in your AI agents, consider supporting ongoing open-source maintenance via GitHub Sponsors.

📄 License

Licensed under the Apache License, Version 2.0 (the "License").
You may not use this software except in compliance with the License.

Copyright © 2026 Prasad Ajinkya and Manthan Contributors.