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

---

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:

Category	Tool Name	Parameters	Description
Entity	create_entities	entities (array of Entity Inputs)	Creates new unique entities with type, domain, and access whitelists.
	delete_entities	names (string array of names)	Removes entities and cascades deletes to their observations and relations.
Relation	create_relations	relations (array of Relation Inputs)	Establishes typed connections (e.g., creator_of, works_on) between entities.
	delete_relations	ids (string array of relation IDs)	Deletes specified relations by ID.
Observation	add_observations	observations (array of Obs Inputs)	Attaches raw observations or LLM-synthesized facts to an entity.
	delete_observations	ids (string array of observation IDs)	Deletes specified observations.
	update_observation	id (string), content (string), changedBy?	Updates observation content while logging the change history.
Query & Graph	search_memory	query (string), limit?	Performs FTS5 BM25 search across entity names, types, and observations.
	read_graph	domain?, entityType?	Retreives the full or filtered knowledge graph snapshot.
	open_nodes	names (string array)	Retrieves full attributes, observations, and relations of specific nodes.
Lifecycle	cleanup_expired	None	Deletes ephemeral observations that have passed their expiration date.
	consolidate_memory	domain?	Performs conflict resolution, near-duplicate Jaccard pruning, and synthesis.
	get_stats	None	Returns storage metrics, entity domain breakdowns, and recent activity logs.
Exporter	export_memory	None	Exports current graph snapshot to active Markdown targets.
	manage_export_targets	action, name?, path?, format?, id?, autoExport?	Registers, removes, or toggles auto-export Markdown paths.
	configure_ai	provider (string)	Changes default AI synthesis provider (none, 9router, ollama, openai).
Universal Bridge	manage_bridge_servers	action (string), name?, command?, args?, id?	Adds, lists, or removes downstream bridged MCP servers in SQLite.
	list_bridge_tools	serverId (string), command?, args?	Queries a bridged server to retrieve its exposed tools.
	call_bridge_tool	serverId (string), toolName (string), arguments?	Executes a tool on a bridged server and returns the result.

---

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)