How do I use Ghostkeep?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Ghostkeep search for facts about the payment gateway migration" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Ghostkeep

by Akshu24Tech

Overview Schema Source Related Servers Discussions Admin

Python

Local

Ghostkeep

Shared, Verifiable Memory for AI Agents

One project memory that every AI agent can read and write verified by deterministic code, not another hallucinating LLM.

Audit CI Python MCP Status Architecture

🎯 The Problem

When working on a modern codebase, developers use multiple AI tools:

Cursor / Windsurf in the IDE
Claude Code in the terminal
Gemini CLI / Antigravity for reasoning & review
Background scripts & workflows

What happens today:

Memory is fragmented: Cursor doesn't know what Claude Code decided 10 minutes ago.
Context amnesia & repetition: You re-explain architectural decisions every time you switch tools.
Naive vector stores hallucinate: Vector similarity matches on outdated phrases; when two agents disagree, they either overwrite each other or blend contradictory rules into silent failures.

Related MCP server: MCP Shared Memory Hub

💡 The Solution: A Verified Register of Claims

Ghostkeep enforces a fundamental golden rule:

"Whoever writes a claim never decides whether it is true."

Instead of trusting agents to self-evaluate, Ghostkeep uses an append-only event ledger and a deterministic code auditor (file existence, AST checks, hash verification, live socket checks) backed by an Applicability Gate:

flowchart TD
    subgraph AgentSurfaces ["🤖 Multi-Agent Development Surfaces"]
        Cursor["Cursor IDE (Editor)"]
        Claude["Claude Code (CLI)"]
        Antigravity["Antigravity / Gemini (Web & Script)"]
    end

    subgraph Ingestion ["1. Event Ingestion (Passive & Ambient)"]
        Hooks["IDE Hooks (.cursor/hooks.json)"]
        Watcher["Watcher (phase0/watcher.py)"]
        EventsLog[("phase0/events.jsonl<br/>Immutable Append-Only Log")]
    end

    subgraph Mining ["2. Claim Extraction"]
        Extractor["phase0/extractor.py<br/>Rule-Based Claim Parser"]
        ClaimsLedger[("phase0/claims.jsonl<br/>Status: unverified")]
    end

    subgraph VerificationEngine ["3. Deterministic Auditor (Zero LLM Guessing)"]
        Auditor["phase0/auditor.py"]
        HashCheck{"SHA-256 Hash<br/>File Check"}
        GitCheck{"Git Commit<br/>cat-file Check"}
        SocketCheck{"Live Socket<br/>Port Listener"}
    end

    subgraph Applicability ["4. Applicability Gate (v2.1 Architecture)"]
        Gate{"Preconditions &<br/>Environment Match?"}
        ConflictLedger[("conflicts.json<br/>Human Review Required")]
    end

    subgraph Serving ["5. Memory Serving & MCP Bus"]
        MemoryMD["MEMORY.md<br/>Concise Active Context (&lt;30 lines)"]
        ClaimsReg["brain/claims_register.md<br/>Human-Readable Table"]
        MCPServer["mcp_server.py<br/>Model Context Protocol 2.x"]
    end

    %% Flow connections
    Cursor --> Hooks
    Claude --> Hooks
    Antigravity --> Watcher
    Hooks --> EventsLog
    Watcher --> EventsLog

    EventsLog --> Extractor
    Extractor --> ClaimsLedger

    ClaimsLedger --> Auditor
    Auditor --> HashCheck & GitCheck & SocketCheck

    HashCheck & GitCheck & SocketCheck -->|Verified| Gate
    HashCheck -->|Hash Mismatch| ClaimsLedger
    
    Gate -->|Mismatch or Conflict| ConflictLedger
    Gate -->|Pass| MemoryMD
    Gate -->|Pass| ClaimsReg

    MemoryMD --> MCPServer
    MCPServer -.->|tools: get_project_memory| Cursor
    MCPServer -.->|tools: query_claims, audit| Claude
    MCPServer -.->|tools: get_project_memory| Antigravity

    classDef surface fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef storage fill:#0f172a,stroke:#64748b,stroke-width:2px,color:#f8fafc;
    classDef engine fill:#1e1b4b,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
    classDef gate fill:#3b0764,stroke:#c084fc,stroke-width:2px,color:#f8fafc;
    classDef serve fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc;

    class Cursor,Claude,Antigravity surface;
    class EventsLog,ClaimsLedger,ConflictLedger storage;
    class Extractor,Auditor,HashCheck,GitCheck,SocketCheck engine;
    class Gate gate;
    class MemoryMD,ClaimsReg,MCPServer serve;

🚀 Quickstart: Unified CLI

Ghostkeep provides a single CLI runner:

1. Check Memory Status

python ghostkeep.py status

Prints total claims, verification breakdown (CHECKED, DECLARED, STALE, INVALID), and rendered MEMORY.md length.

2. Declare a Decision Directly

python ghostkeep.py remember "Always use port 8765 for server"

Immediately declares a human decision, updates the ledger, and renders MEMORY.md.

3. Full Pipeline Sync (Extract → Audit → Render)

python ghostkeep.py sync

Parses recent interaction events, runs the deterministic auditor, transitions changed states (checked -> stale on hash mismatch), and renders the latest MEMORY.md.

🔌 Model Context Protocol (MCP) Server

Ghostkeep includes a native FastMCP server (mcp_server.py) that exposes bidirectional project memory directly to Claude Desktop, Cursor, and Windsurf:

python mcp_server.py

Supported MCP Tools:

get_project_memory(): Returns the latest, concise MEMORY.md (active human decisions + verified facts).
query_claims(status='checked', kind='verifiable'): Filter claims by verification status and category.
remember_claim(text='...', kind='decision'): Allows agents to declare architectural rules directly into persistent memory.
forget_claim(claim_id='C-003', reason='...'): Deprecates an obsolete claim so it stops polluting active context.
audit_memory(): Triggers an on-demand re-audit of the codebase and returns the refreshed memory ledger.

Claude Desktop / Cursor Config (`mcp.json`):

{
  "mcpServers": {
    "ghostkeep": {
      "command": "python",
      "args": ["E:\\Ghost OS\\projects\\ghostkeep\\mcp_server.py"]
    }
  }
}

🛡️ Architecture Highlights (v2.1)

Feature	Implementation	Why It Matters
Separation of Concerns	Agent proposes claims (`unverified`), code verifies (`checked`)	Eliminates LLM self-grading bias and hallucinations.
Tamper-Evident Drift	SHA-256 hash tracking on referenced files	When a file changes, claims automatically transition from `checked` to `stale`.
Applicability Gates	Staged conflict ledger (`conflicts.json`)	Contradictory policies are surfaced to the human operator, never silently blended.
Append-Only Truth	`events.jsonl` + `claims.jsonl`	If markdown views or vaults get damaged, they can be 100% regenerated from the log.

📁 Repository Structure

ghostkeep/
├── .github/workflows/
│   └── audit.yml              # 🤖 Automated Memory Audit CI on push/PR
├── ghostkeep.py               # 🚀 Unified CLI (status, sync, audit, extract)
├── mcp_server.py              # 🔌 Native FastMCP Server for Claude/Cursor/Windsurf
├── MEMORY.md                  # 🧠 Concise rendered memory view (max 60 lines)
├── requirements.txt           # Core server dependencies (FastMCP, Pydantic)
├── ARCHITECTURE_v2.1.md       # In-depth architectural blueprint
├── PROJECT.md                 # Product roadmap & operational goals
├── phase0/
│   ├── events.jsonl           # Append-only event source of truth
│   ├── claims.jsonl           # Persistent claim ledger with hashes & states
│   ├── watcher.py             # Passive transcript & git interaction tailer
│   ├── extractor.py           # Rule-based claim extractor
│   ├── auditor.py             # Deterministic verification engine
│   └── render_memory.py       # MEMORY.md generator
└── brain/
    └── claims_register.md     # Full human-readable markdown table of all claims

👨‍💻 Author

Akshu Grewal
Agentic AI Engineer specializing in verifiable, reliable tool-using systems.

GitHub: @Akshu24Tech

This server cannot be deployed

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

Related MCP Connectors

memnodeOAuth
dev.memnode
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Knowledge & Memory Autonomous Agents Agent Orchestration
2
https://api.memnode.dev/mcp
KogniteOAuth
dev.kognite
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Knowledge & Memory RAG Systems
1
https://mcp.kognite.dev/mcp
Cairn.ink MemoryOAuth
ink.cairn
Cross-session memory for AI agents with a Source Receipt for every memory, over MCP.
Knowledge & Memory RAG Systems
131
https://cairn.ink/api/mcp
khiveOAuth
ai.khive
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Knowledge & Memory Project Management
1
https://khive.ai/v1/mcp

Related MCP Servers

Synapto
Knowledge & Memory Search
ramonlimaramos
A
license
Not graded
quality
A
maintenance
Provides persistent, searchable memory for MCP-compatible agents, enabling recall by meaning, automatic decay, trust scoring, and cross-agent handoffs.
Updated 2 months ago (2026-09-07 16:58 UTC)
21 PyPI
5
MIT
MCP Shared Memory Hub
Knowledge & Memory RAG Systems
shirisha456
A
license
Not graded
quality
C
maintenance
Enables multiple MCP-compatible AI clients to share persistent, versioned project knowledge across sessions with conflict-safe updates, provenance, hybrid retrieval, stale-memory handling, and context-budgeted recall.
Updated 2 months ago (2026-08-31 03:52 UTC)
MIT
marrow
Knowledge & Memory RAG Systems
aryawidjaja
A
license
Not graded
quality
B
maintenance
Provides persistent, shared memory for AI agents via MCP, enabling retrieval of relevant memories instead of loading entire context. Allows agents across projects, machines, and tools to share a single auditable, markdown-native brain.
Updated 3 months ago (2026-08-12 07:13 UTC)
3
AGPL 3.0
cairn
Knowledge & Memory RAG Systems
veridian69
A
license
Not graded
quality
B
maintenance
Enables self-hosted, provenance-aware shared memory with scoped access, attributed observations, correction history, disagreement tracking, and durable idempotent writes for humans and AI agents via REST and MCP.
Updated 10 days ago (2026-10-21 04:51 UTC)
1
Apache 2.0

Ghostkeep

🎯 The Problem

What happens today:

💡 The Solution: A Verified Register of Claims

🚀 Quickstart: Unified CLI

1. Check Memory Status

2. Declare a Decision Directly

3. Full Pipeline Sync (Extract → Audit → Render)

🔌 Model Context Protocol (MCP) Server

Supported MCP Tools:

Claude Desktop / Cursor Config (mcp.json):

🛡️ Architecture Highlights (v2.1)

📁 Repository Structure

👨‍💻 Author

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Synapto

MCP Shared Memory Hub

marrow

cairn

Claude Desktop / Cursor Config (`mcp.json`):