Content
# Amneshia
[](https://github.com/SabilMurti/Amneshia/releases)
[](LICENSE)
[](https://github.com/SabilMurti/Amneshia/actions)
[](https://github.com/SabilMurti/Amneshia/actions)
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:
```mermaid
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:
```bash
# 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:
```bash
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`):
```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**](https://github.com/DeusData/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`):
```markdown
### 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)
