Amneshia

Unified, zero-external-database, multi-agent long-term memory hub. Built on top of SQLite FTS5 + BM25 Search, incorporating a Universal MCP Bridge Manager, a local Sleep Cycle Memory Consolidation Engine, and an interactive Amneshia Web Dashboard.

Architecture Diagram

Amneshia coordinates Stdio and SSE/HTTP transports, managing underlying storage, background consolidation tasks, and MCP integrations:

flowchart TB
    %% Class Definitions for Styling
    classDef client fill:#1e1e2e,stroke:#a855f7,stroke-width:2px,color:#fff;
    classDef transport fill:#1e1e2e,stroke:#06b6d4,stroke-width:2px,color:#fff;
    classDef core fill:#181825,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef bridge fill:#1e1e2e,stroke:#f59e0b,stroke-width:2px,color:#fff;
    classDef db fill:#11111b,stroke:#10b981,stroke-width:2px,color:#fff;

    subgraph Clients ["1. Clients & Agent IDEs"]
        Agent["🤖 AI Agents (Antigravity IDE / Cursor / Windsurf / Claude Code)"]:::client
        Browser["🌐 Amneshia Web Dashboard (React 18 + Vite)"]:::client
    end

    subgraph Transport ["2. Transport & Communication Layer"]
        Stdio["⚡ Stdio Transport (JSON-RPC 2.0)"]:::transport
        SSE["🌐 HTTP / SSE Server (Port 3457)"]:::transport
        REST["🔗 REST API Endpoints"]:::transport
    end

    subgraph Amneshia ["3. Amneshia v2 Core Knowledge Engine"]
        MCP["🛠️ 18 MCP Tools Surface"]:::core
        Graph["Knowledge Graph Engine"]:::core
        Sleep["🌙 Sleep Cycle Consolidation Engine"]:::core
        Exporter["📄 Markdown Auto-Exporter"]:::core
        DB[("💾 SQLite FTS5 Storage (~/.amneshia/memory.db)")]:::db
    end

    subgraph Bridges ["4. Universal MCP Bridge System"]
        Bridge["🔌 Bridge Client Manager"]:::bridge
        CM["💻 codebase-memory-mcp (Port 9749)"]:::bridge
        Other["🌐 External Custom MCP Servers"]:::bridge
    end

    %% Flow Connections
    Agent <-->|Stdio Stream / SSE| Transport
    Browser <-->|HTTP REST API| REST

    Stdio <-->|JSON-RPC| MCP
    SSE <-->|HTTP Events| REST
    REST <-->|API Handler| Graph

    MCP <-->|CRUD & FTS Queries| Graph
    Graph <-->|BM25 Search & SQL Triggers| DB
    Sleep <-->|Jaccard Pruning & Conflict Supersession| DB
    Graph -->|Sync Markdown Mirror| Exporter

    Graph <-->|Bridge Proxy Tools| Bridge
    Bridge <-->|Auto-Sync Projects| CM
    Bridge <-->|Proxy Tool Call| Other

Related MCP server: alaya

Key Features

• Semantic Knowledge Graph — Not a simple, flat key-value store. Entities are organized using structured, typed relationships and observations.

• FTS5 BM25 Search — Integrates SQLite FTS5 extension with BM25 ranking for fast, typo-tolerant full-text query lookup.

• Universal MCP Bridge — Interoperability with external MCP servers (such as codebase-memory-mcp) allowing synchronization of external facts and tools dynamically.

• Sleep Cycle Memory Consolidation — Evaluates similarity metrics (Jaccard Similarity $\ge 0.8$) and LLM context analysis during sleep/idle states to deduplicate memories, resolve conflicts, track update histories, and purge expired ephemeral data.

• Access Control Whitelisting — Visibility properties (public, restricted, private) and whitelisting arrays (allowedAgents) prevent unauthorized agent access.

• Amneshia Web Dashboard — Rich visual interface built with TasteSkill anti-slop guidelines for exploring graphs, managing target exports, controlling bridge servers, and viewing memory statistics.

Quick Start

1. Direct Run via GitHub

You can run Amneshia instantly from GitHub without installing anything:

# Run HTTP Web Dashboard & REST API in background daemon mode
amneshia --http --port 3457 --daemon

# Or via npx directly from GitHub:
npx -y github:SabilMurti/Amneshia --http --port 3457 --daemon

Or install globally via GitHub:

npm install -g github:SabilMurti/Amneshia

# Run in background daemon mode anywhere:
amneshia --http --daemon

2. Stdio Mode (Standard IDE Integration)

To connect Amneshia to your editor/agent environment (e.g., Cursor, Antigravity IDE, Claude Code), add the server entry in your MCP config (mcp_config.json):

{
  "mcpServers": {
    "amneshia": {
      "command": "npx",
      "args": ["-y", "github:SabilMurti/Amneshia"]
    }
  }
}

Complete MCP Tools Reference (18 Tools)

Amneshia exposes 18 specialized tools to client agents for managing the memory cycle, querying data, and bridging other servers:

Web Dashboard & Codebase Integration

Amneshia serves a web client on http://localhost:3457 when running in HTTP mode. The client provides:

1. Interactive Graph Visualizer for looking at entity links and node clusters.

2. Bridge Manager to register downstream MCP servers (e.g. codebase-memory-mcp) and configure commands/args.

3. Settings Controls to switch LLM Providers (9router AG, Ollama, OpenAI, or None) and manage auto-export markdown logs.

Codebase Memory MCP Bridge Sync

codebase-memory-mcp is an advanced MCP server by DeusData that creates structural codebase knowledge graphs (AST analysis, function signatures, dependency trees, and git metadata) for AI agents.

When codebase-memory-mcp is configured as a bridge server in Amneshia and enabled, the system supports 1-click cross-graph synchronization via the /api/bridge/sync REST endpoint (or call_bridge_tool). This triggers an automated scan of the bridged server's active codebase indices, importing:

• Workspace root paths.

• Codebase nodes and edges metrics.

• Active git branches and commit SHAs.

These synchronized details are stored directly under the project entity's observations prefixed with [Codebase Memory MCP].

Recommended Agent Directives / System Rules

To give your AI Agent (Cursor, Antigravity IDE, Claude Code, Windsurf, etc.) optimal long-term memory behavior, copy and paste the following prompt rules into your agent's custom instructions file (e.g. GEMINI.md, CLAUDE.md, .cursorrules, AGENTS.md):

### Long-Term Memory & Knowledge Graph Directives (Amneshia)
You are equipped with **Amneshia** (`amneshia`), a zero-external-database SQLite FTS5 long-term memory hub and Knowledge Graph.

1. **Session-Start Memory Retrieval**:
   - At the beginning of a conversation or session, call `search_memory` or `read_graph` to recall user context, active project preferences, entity relationships, and architectural decisions.
2. **Proactive Fact & Preference Persistence**:
   - Whenever the user shares a new preference, personal detail, workflow choice, or project update, proactively invoke `add_observations` or `create_entities` to store it permanently in Amneshia.
3. **Conflict Resolution & Consolidation**:
   - When user preferences change or old statements are updated, append the revision via `add_observations`, or call `consolidate_memory` ("Sleep Cycle") to track update histories and supersede outdated memories automatically.

License

MIT © Sabil Murti (Murtix)