How do I use Amneshia?

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., "@Amneshia Remember that I prefer dark mode" 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.

Amneshia

by SabilMurti

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Technical Summary

Amneshia is a local-first memory engine for AI coding agents (Claude Desktop, Cursor, Antigravity, Windsurf) implementing the Model Context Protocol (MCP).

It replaces probabilistic, vector-only memory systems with a deterministic Truth Maintenance System (TMS) backed by embedded SQLite FTS5 and human-readable Markdown files.

Zero LLM Calls inside the Engine: Retrieval, conflict detection, decay calculation, and deduplication execute locally in < 1ms via SQLite FTS5 and rule-based token analysis. Zero external tokens consumed.
Markdown-as-Truth (.amneshia/knowledge/): All entities and observations mirror directly to version-controlled Markdown files with YAML frontmatter. Auditable via git diff and reviewable in Pull Requests.
Truth Maintenance & Cascading Invalidation: Derived facts track their premises via directed acyclic graphs (derived_from: [parent_id]). When a premise is revoked or updated, dependent conclusions automatically transition from active to stale.
Pre-Insertion Contradiction Detection: Evaluates incoming facts against active entity records for polar opposition and explicit replacements, rejecting or logging conflicts before graph corruption occurs.
Lean Context Budget (85% Reduction): Default 4-tool surface (remember, recall, forget, context) reduces prompt schema consumption from ~5,400 tokens to ~800 tokens.

Related MCP server: Graph-Memory

⚡ Quickstart & IDE Setup

Installation Options

Option A: Universal One-Liner (Recommended)

curl -fsSL https://raw.githubusercontent.com/SabilMurti/Amneshia/main/install.sh | bash

npm install -g https://github.com/SabilMurti/Amneshia/releases/latest/download/amneshia-latest.tgz

Option C: JSR (TypeScript / Deno / Bun / Node)

# Add to project via JSR
npx jsr add @sabilmurti/amneshia
# or with Bun
bunx jsr add @sabilmurti/amneshia

Option D: GitHub Packages (`npm.pkg.github.com`)

# Add scope registry config to ~/.npmrc (once):
# @sabilmurti:registry=https://npm.pkg.github.com
npm install -g @sabilmurti/amneshia

Option E: Build from Source

git clone https://github.com/SabilMurti/Amneshia.git
cd Amneshia
npm install
npm run build && npm install -g .

MCP Client Configurations

Add Amneshia to your favorite MCP host configuration:

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "amneshia": {
      "command": "amneshia",
      "args": ["--tool-profile", "core"]
    }
  }
}

Cursor (`.cursor/mcp.json`)

{
  "mcpServers": {
    "amneshia": {
      "command": "amneshia",
      "args": ["--tool-profile", "core", "-l"]
    }
  }
}

(Passing -l or --local scopes memory to .amneshia/ within the active working directory).

Google Antigravity IDE (`mcp_config.json`)

{
  "mcpServers": {
    "amneshia": {
      "command": "amneshia",
      "args": ["--tool-profile", "core"]
    }
  }
}

Windsurf (`mcp_config.json`)

{
  "mcpServers": {
    "amneshia": {
      "command": "amneshia",
      "args": ["--tool-profile", "core", "-l"]
    }
  }
}

VS Code (Roo Code / Cline / Continue)

{
  "mcpServers": {
    "amneshia": {
      "command": "amneshia",
      "args": ["--tool-profile", "core"]
    }
  }
}

30-Second Verification

# 1. Initialize local repository knowledge graph
amneshia init

# 2. View knowledge graph statistics
amneshia stats

# 3. Launch interactive 3D Web Dashboard (runs on http://localhost:3457)
amneshia serve

📑 Table of Contents

The Problem with Existing Agent Memory

Modern agent memory implementations fall into three flawed paradigms:

1. The "LLM-in-LLM" Antipattern

Systems like Mem0 or Zep invoke an external LLM inside the memory engine to summarize, deduce, or reconcile facts.

Latency Penalty: Every memory query triggers an HTTP request to an inference endpoint, taking 2,000–5,000ms.
Stochastic Mutation: Re-summarizing facts through a probabilistic model introduces hallucination risk and strips away exact technical specifications (e.g. port numbers, compiler flags, exact variable names).
Fragile Setup: Demands API keys, cloud credits, or local Ollama servers running in the background.

2. State Invalidation Failure in Vector Databases

Vector similarity search computes cosine distances between text embeddings. It has no concept of state transition over time ($A \to \neg A$).

If an agent stores "Database is PostgreSQL" on Monday, and "Switched database to SQLite" on Wednesday, a vector query for "database setup" returns both embeddings with near-identical similarity scores ($0.88$ vs $0.86$).
The calling model receives contradictory facts in its context window and hallucinates mixed architectures.

3. Opaque Storage Lock-in

Storing memory in proprietary cloud databases or binary embeddings makes it impossible for engineering teams to inspect, debug, or edit what an AI agent has remembered about a codebase.

Architectural Comparison: MCP Memory Ecosystem

Capability	Amneshia v3	Official `@modelcontextprotocol/server-memory`	`memori-mcp`	`pgvector` Memory MCP	`Memento` (Neo4j MCP)	`Supermemory` MCP
Zero External Infrastructure	Yes (Embedded SQLite)	Yes (Flat JSON file)	Yes	❌ (Requires Docker PostgreSQL)	❌ (Requires Neo4j Server)	❌ (Requires Cloud API Key)
Engine Token Burn	0 tokens ($0.00)	0 tokens	0 tokens	0 tokens	0 tokens	❌ (Consumes cloud tokens)
Query Latency	< 1ms (SQLite FTS5)	Linear file scan	Relational scan	50–120ms (HNSW index)	20–60ms (Cypher query)	1,500–3,500ms (HTTP round-trip)
Markdown-as-Truth (Git)	Yes (`.amneshia/knowledge/`)	❌ (Single `memory.json`)	❌ (No file truth)	❌ (PostgreSQL binary tables)	❌ (Neo4j binary graph)	❌ (Proprietary cloud storage)
Truth Maintenance (TMS)	Yes (Authority Tiers)	❌ (None)	❌ (None)	❌ (None)	❌ (None)	❌ (None)
Cascading Invalidation	Yes (Recursive DAG)	❌ (None)	❌ (None)	❌ (None)	❌ (None)	❌ (None)
Contradiction Detection	Yes (Pre-insertion scan)	❌ (None)	❌ (None)	❌ (None)	❌ (None)	❌ (None)
Relational Traversal	Yes (GraphRAG Multi-Hop)	⚠️ (Basic string graph)	❌ (Tool call history)	❌ (Flat vector only)	Yes (Cypher traversal)	⚠️ (Basic entity linking)
Token Budgeting	Yes (Enforced byte limits)	❌ (Dumps raw nodes)	⚠️	❌ (Top-K raw dump)	❌ (Uncapped subgraphs)	⚠️
Interactive Dashboard	Yes (Three.js on port 3457)	❌ (No UI)	❌ (No UI)	❌ (No UI)	⚠️ (Neo4j Desktop browser)	Yes (Cloud-hosted UI)

Core Systems Deep Dive

1. Truth Maintenance System (TMS)

Authority Tiers

Every observation is tagged with an authority level that dictates its lifecycle and eviction priority:

Tier	Weight	Inactivity Threshold	Eviction Behavior	Intended Usage
`invariant`	`1.0`	∞	Never decays	User hard requirements, security rules, immutable architecture constraints.
`architectural`	`0.8`	365 days	Transitions to `decayed`	Framework choices, database schemas, structural API contracts.
`contextual`	`0.5`	90 days	Transitions to `decayed`	Current working conventions, active versions, environment configs.
`ephemeral`	`0.2`	7 days / TTL	Hard purged on GC	Scratchpad notes, temporary debug logs, short-lived task state.

Mathematical Decay Scoring

Decay evaluation runs deterministically during maintenance or GC passes:

$$\text{DecayScore} = w_{\text{tier}} \times \left(1 + \log_{10}(\text{accessCount} + 1)\right) \times \max\left(0, 1 - \frac{\text{daysInactive}}{\text{maxDays}}\right)$$

Observations where $\text{DecayScore} < 0.1$ are transitioned from active to decayed, excluding them from active search queries while preserving audit lineage.

Cascading Invalidation DAG

When an agent registers an observation that relies on previous facts, it declares derived_from: ["<uuid>"].

If a root observation is marked superseded or invalidated:
1. The engine identifies all direct and transitive children via breadth-first search across the dependency graph.
2. All descendants transition status: active → stale.
3. Stale observations are filtered out from default recall queries, preventing downstream reasoning errors.

Pre-Insertion Contradiction Detection

Incoming facts pass through a zero-latency semantic filter prior to database insertion:

Tokenization: Text is normalized, lowercased, stripped of punctuation, and tokenized into distinct lexemes.
Polarity Check: Scanned against explicit negation patterns (not, never, no longer, instead of, deprecated, removed, disabled).
Opposition Evaluation: If token overlap between an incoming fact and an active fact on the same entity exceeds ≥ 50%, and one statement contains negation while the other does not, a contradiction event is recorded in contradiction_log and returned as a warning payload to the calling agent.

2. Dual-Write Storage: Markdown-as-Truth

Amneshia operates a dual-write architecture:

Write Path: Graph mutations write simultaneously to SQLite and serialize to human-readable Markdown files located in .amneshia/knowledge/{domain}/{entity}.md.
Recovery Path: If the SQLite cache is deleted or desynced, amneshia reindex reconstructs the entire FTS5 database directly from the Markdown directory in < 200ms.

Sample Entity File (`.amneshia/knowledge/backend/database.md`):

---
id: "8f7e2a1b-3c4d-4e5f-9a0b-1c2d3e4f5a6b"
name: "Production Database"
type: "infrastructure"
domain: "backend"
visibility: "public"
created: "2026-09-28T10:00:00.000Z"
updated: "2026-09-28T18:30:00.000Z"
---

## Observations

- **[invariant]** Primary database is PostgreSQL 16 hosted on AWS RDS
  `id: obs-001 | confidence: 1.0 | status: active`

- **[architectural]** Connection pooling configured via PgBouncer with pool_size = 25
  `id: obs-002 | confidence: 0.9 | derived_from: [obs-001] | status: active`

- ~~**[contextual]** SQLite used for local prototype development~~
  `id: obs-003 | confidence: 0.5 | status: superseded | superseded_by: obs-001`

## Relations

- `depends_on` -> AWS VPC Security Group
- `monitored_by` -> Datadog Agent

3. Tool Surface & JSON-RPC Schemas

When initialized with --tool-profile core (default), Amneshia exposes 4 high-level MCP tools:

MCP Toolset (Core Profile)
├── remember  : Entity upsert, observation recording, contradiction checks
├── recall    : BM25 full-text search with token budgeting
├── forget    : Soft/hard invalidation with dependency cascade
└── context   : GraphRAG multi-hop relational traversal

`remember`

{
  "name": "remember",
  "arguments": {
    "entity": "Authentication",
    "facts": ["JWT access tokens expire after 15 minutes", "Refresh tokens stored in HTTP-only cookies"],
    "tier": "architectural",
    "derived_from": ["obs-001"]
  }
}

`recall`

{
  "name": "recall",
  "arguments": {
    "query": "JWT expiration window",
    "token_budget": 1000,
    "depth": 1
  }
}

`forget`

{
  "name": "forget",
  "arguments": {
    "target": "obs-002",
    "hard": false,
    "cascade": true
  }
}

`context`

{
  "name": "context",
  "arguments": {
    "query": "Authentication",
    "depth": 2,
    "limit": 5
  }
}

(For low-level entity and relation CRUD operations, specify --tool-profile full during server launch).

3D Web Dashboard (Port 3457)

Amneshia ships with a zero-dependency web dashboard built with React 18, Vite, and Three.js ForceGraph, pre-compiled into dist-ui/:

🌌 3D Neural Universe View

Force-directed spatial graph layout of all entities and typed edges, color-coded by architectural domain with real-time neural physics controls (repulsion force, synapse distance, and domain filtering).

🔍 Memory Inspector & Truth Maintenance View

Granular observation inspector filterable by Authority Tier (invariant, architectural, contextual, ephemeral) and DAG status (active, stale, invalidated, superseded). Supports observation auditing, access counter inspection, conflict resolution, and one-click Markdown sync.

Launching the Dashboard

# Launch server with dashboard on port 3457
amneshia serve --port 3457

# Open in browser: http://localhost:3457

Agent System Rules & Prompt Presets

To ensure your coding agents (Cursor, Claude Code, Windsurf, Antigravity) actively read, persist, and maintain project memory throughout their lifecycle without human prompting, add this preset rule block to your project configuration (e.g. .cursor/rules/amneshia.mdc, .cursorrules, CLAUDE.md, .windsurfrules, or AGENTS.md):

# Long-Term Memory Directives (Amneshia Engine)

You are connected to **Amneshia** (`amneshia`), an enterprise-grade SQLite FTS5 long-term memory engine with a deterministic Truth Maintenance DAG. You MUST adhere to the following memory lifecycle for every coding task:

## 1. Pre-Flight Retrieval (Start of Every Session & Task)
- **Mandatory Recall:** Before writing code, planning refactors, or suggesting libraries, ALWAYS query Amneshia using `recall(query: "<topic/keyword>")` or inspect project context via `context(categories: ["architecture", "preference"])`.
- **Never Guess Conventions:** Verify past architectural decisions, repository quirks, coding styles, and active credentials before scaffolding.

## 2. In-Flight Execution & Authority Hierarchy
- **Authority Levels:** Amneshia enforces strict tiers: `system` (3) > `user` (2) > `agent` (1).
- **No Overwriting User Directives:** As an agent, your writes default to `agent` authority. Never try to supersede or contradict user-defined decisions without explicit user consent.
- **Contradiction Alerts:** If `remember` returns a contradiction alert (e.g. conflicting framework version or competing state library), halt and clarify with the user.

## 3. Post-Flight Persistence (End of Every Completed Task — Exhaustive & Detailed)
- **Proactive Auto-Memory:** Upon successfully completing a task, implementing a feature, or fixing a bug, you MUST proactively call `remember()` to persist a comprehensive debrief.
- **Strict Anti-Shallow Rule:** NEVER output lazy, one-line summaries (e.g. bans like *"Fixed bug in UI"* or *"Updated config"*). 
- **Mandatory Debrief Structure:** Every stored observation must provide exhaustive technical density:
  1. **Context & Rationale:** Problem statement, user intent, and why the solution was designed this way.
  2. **Technical Implementation:** Concrete file paths modified, core components/classes built, algorithms chosen, and schema migrations applied.
  3. **Operational Parameters:** Ports, endpoints, CLI parameters, and environment variable requirements.
  4. **Verification & Test Outcomes:** Exact test suites run, number of passing assertions, and edge cases handled.
  5. **Architectural Guardrails:** Traps, caveats, and conventions that future agents must follow to avoid regressions.
- **Example Call:**
  `remember(content: "Dashboard port changed to 3457 to prevent conflicts with Vite default. Modified src/server.ts and src/index.ts to pass stdio: false on serve subcommand, preventing terminal background job suspensions. Verified with curl /api/stats (200 OK) and 30/30 vitest assertions passing.", category: "architecture", entity_name: "amneshia", importance: 9, tags: ["networking", "dashboard", "cli"])`

## 4. Soft Invalidation Over Deletion
- **Never Leave Stale Memory:** If a prior decision, dependency, or file path is deprecated or replaced, call `forget(observation_id: "<id>", reason: "<why it is deprecated>")`.
- Amneshia automatically marks the node as `stale`/`invalidated` in the DAG while preserving audit lineage.

## 5. Dual-Write Transparency
- All stored memories are dual-written to `.amneshia/knowledge/**/*.md`. You may inspect or commit these files directly with git.

CLI Reference

# Scaffold .amneshia/ directory and .gitignore in current workspace
amneshia init

# Rebuild SQLite FTS5 database from .amneshia/knowledge/ Markdown files
amneshia reindex

# Display memory storage statistics and authority tier breakdown
amneshia stats

# Purge expired and decayed observations
amneshia gc

# Run Web Dashboard server on port 3457
amneshia serve -p 3457

# Launch as a background daemon process
amneshia --background

Verified Test Suite

$ npm test

 ✓ tests/graph.test.ts (2 tests)
 ✓ tests/database.test.ts (8 tests)
 ✓ tests/storage.test.ts (5 tests)
 ✓ tests/consolidation.test.ts (5 tests)
 ✓ tests/tools.test.ts (4 tests)
 ✓ tests/api.test.ts (3 tests)
 ✓ tests/cli.test.ts (3 tests)

 Test Files  7 passed (7)
      Tests  30 passed (30)
   Duration  2.65s

Design Non-Goals & Architectural Boundaries

To maintain sub-millisecond execution and total determinism, Amneshia explicitly rejects:

Embedding Ingestion of Large Arbitrary Blobs: Amneshia is an agent knowledge graph and decision store, not an unstructured PDF semantic search engine. Use dedicated vector databases (e.g. Qdrant) for raw document embeddings.
Distributed Multi-Writer Consensus: Designed as a local-first single-writer engine. Team collaboration is handled natively through Git pull requests on .amneshia/knowledge/ Markdown files.
Probabilistic LLM Processing in the Core Engine: Conflict resolution and decay scoring are strictly mathematical and rule-based. The calling agent is the reasoning layer; the memory engine is the ground truth.

Contributing & Community

Amneshia is open source under the MIT License. Contributions, bug reports, and architectural RFCs are welcome.

📖 Contributor Guidelines: See CONTRIBUTING.md for local environment setup, architecture standards, and PR workflows.
💬 GitHub Discussions: Ask questions, share workflows, and discuss features in GitHub Discussions.
🐛 Issue Tracker: Submit bug reports and feature proposals via GitHub Issues.

License

MIT © Sabil Murti

Available Tools

4 tools

contextA

Traverse the knowledge graph starting from query seed entities outward up to N hops using GraphRAG relational discovery.

WHEN TO USE:

Use "context" when you need holistic, multi-hop relational knowledge around an entity (e.g. architecture, connections, dependencies).
DO NOT use for simple keyword search or strict token-budget lookups — use "recall" instead.

RETURNS:

Formatted relational Markdown document detailing seed entities, their attributes, active observations, and outward relation links.

ParametersJSON Schema

Name	Required	Description
`depth`	No	Traversal depth (default: 1)
`limit`	No	Maximum seed entities (default: 5)
`query`	Yes	Search query for starting seeds
`domain`	No	Optional domain filter

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It helpfully discloses the return format (relational Markdown with seeds, attributes, observations, links) and the hop-based traversal model, but says nothing about cost/performance of deep traversal, rate limits, or how an empty/partial match is handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded one-line purpose followed by labeled WHEN TO USE and RETURNS sections; every sentence carries routing or payload information with no filler beyond minor wording repetition ('relational' twice).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter tool with no output schema, the description supplies the return shape and traversal semantics, which is most of what an agent needs. It omits the 'domain' filter's effect and any note on how depth interacts with result volume.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters (query, depth, limit, domain) are already documented in the schema with defaults and bounds. The description only maps 'N hops' to depth and 'seed entities' to limit, adding marginal meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Traverse the knowledge graph') plus the mechanism ('GraphRAG relational discovery') and scope ('outward up to N hops'). An agent can distinguish it from the sibling 'recall' without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit WHEN TO USE section names the qualifying scenario (holistic multi-hop relational knowledge) and a DO NOT case with a named alternative ('use recall instead' for keyword search or token-budget lookups). This is exactly the routing guidance an agent needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

forgetA

Invalidate or permanently remove an entity or a specific observation UUID. Supports soft invalidation, hard permanent deletion, and automatic cascading invalidation of dependent facts.

WHEN TO USE:

Use "forget" when a fact is superseded, contradicted, or deprecated.
Prefers soft invalidation (hard=false) to preserve audit trails. Use hard=true only when permanently expunging sensitive data.
DO NOT use to update a fact with new info — use "remember" with updated content.

PERMISSIONS & FAILURE BEHAVIOR:

Operates locally on SQLite storage. Returns an error if the target entity name or UUID is not found in the database.
Returns JSON containing { ok: true, type, targetId/entity, mode, cascadedStaleCount }.

ParametersJSON Schema

Name	Required	Description
`hard`	No	true = permanent delete from database; false = mark invalidated (default)
`target`	Yes	Entity name OR observation UUID to forget
`cascade`	No	true = also invalidate facts derived from this target (default: true)

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses local SQLite storage, the error returned when the target is not found, the irreversibility implied by hard=true permanent expunging, cascade semantics, and even the response shape (ok/type/targetId/mode/cascadedStaleCount). This covers safety, failure, and side-effect behavior an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded one-line purpose followed by labeled sections for usage and failure behavior; every sentence carries actionable content with no filler. The structure lets an agent scan the trigger, the mode trade-off, and the exclusion quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter mutation tool with no annotations and no output schema, the description supplies everything missing: when to use, when not to, preference between modes, error behavior, cascade behavior, and a description of the return payload. No relevant gap remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds genuine meaning by explaining the soft (audit-preserving) vs hard (permanent expunge) mode distinction for 'hard' and the dependent-fact invalidation for 'cascade'. It stops short of detailing the 'target' string format beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names the exact operation (invalidate or permanently remove) and the two target types (entity or observation UUID), plus the cascading behavior. It clearly differentiates from siblings by naming remember as the tool for updating facts, so an agent can route without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit WHEN TO USE section: forget when a fact is superseded/contradicted/deprecated, prefers soft invalidation (hard=false), hard=true only for sensitive data, and an explicit DO NOT clause pointing to the remember alternative. Both the positive trigger and the exclusion are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recallA

Search memory observations and facts matching keywords or concepts using SQLite FTS5 BM25. Enforces a strict token budget to prevent context window overflow.

WHEN TO USE:

Use "recall" for focused keyword search, retrieving specific past facts, or when under a strict token budget.
DO NOT use for exploring structural, multi-hop entity relationships — use "context" instead.

RETURNS:

JSON object containing matched entities, facts with authority tiers and statuses, estimated tokens used, and truncation flag.

ParametersJSON Schema

Name	Required	Description
`depth`	No	Graph expansion depth (0 = flat search, 1+ = multi-hop GraphRAG)
`query`	Yes	Query text to search across facts and entities
`domain`	No	Filter by domain
`token_budget`	No	Maximum tokens to return (default: 2000)

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and mostly delivers: it discloses the token budget enforcement, the context-window-overflow protection, result truncation, and that results carry authority tiers and statuses. It does not state side-effect profile (read-only) or any rate/permission constraints, but the disclosed behavior goes well beyond what the schema provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose in one sentence, then uses compact WHEN TO USE and RETURNS sections. Every sentence is functional; the only mildly extraneous detail is the FTS5/BM25 implementation name, which is cheap and still useful for understanding ranking behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description compensates by describing the return payload (matched entities, facts with authority tiers and statuses, token usage, truncation flag). Combined with the routing guidance, this is essentially complete; only the read-only/no-side-effect guarantee is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so depth, query, domain, and token_budget are already documented in the schema. The description reinforces the token budget concept but adds no syntax, default semantics, or interaction details (e.g., how depth interacts with BM25) beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) plus resource (memory observations and facts) and even the matching mechanism (SQLite FTS5 BM25). It explicitly distinguishes itself from the sibling 'context' tool for structural/multi-hop queries, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Contains an explicit WHEN TO USE block with positive conditions (focused keyword search, retrieving specific facts, token-constrained situations) and a negative condition (DO NOT use for structural multi-hop relationships) that names the alternative tool. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rememberA

Store one or more factual observations under an entity in the knowledge graph. Automatically creates the entity if missing, evaluates pre-insertion contradiction detection against existing facts, assigns authority tiers, and records logical dependencies.

WHEN TO USE:

Use "remember" to record new knowledge, user preferences, architectural decisions, or verified facts.
DO NOT use to invalidate or delete outdated facts — use "forget" instead.
DO NOT use to query memory — use "recall" or "context" instead.

CONTRADICTION & RETURN BEHAVIOR:

Evaluates semantic opposition. If a contradiction is detected, a warning is returned and recorded in the audit log while persisting the fact.
Returns JSON containing { ok: true, entity, domain, tier, observationIds, contradictionWarnings }.

ParametersJSON Schema

Name	Required	Description
`tier`	No	Authority tier: invariant (never decays), architectural (365d), contextual (90d), ephemeral (7d)
`type`	No	Entity type (default: "concept")
`facts`	Yes	List of facts/observations to remember
`domain`	No	Domain namespace (default: "personal")
`entity`	Yes	Entity name (e.g. "React Architecture", "Sabil Murti")
`derived_from`	No	Observation IDs that these facts logically depend on (for truth maintenance)

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so: auto-creation of missing entities, pre-insertion contradiction detection, authority-tier assignment, dependency recording, and the policy of persisting the fact while emitting a warning on contradiction. It also documents the side effect of audit-log recording and the return shape, which is exactly the kind of mutation/return transparency a no-annotation tool needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then cleanly sectioned into trigger and behavior blocks. Every line earns its place — the routing lines and the contradiction/return note each carry information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite six parameters and no output schema, the description supplies the return JSON keys (ok, entity, domain, tier, observationIds, contradictionWarnings) and the contradiction warning path. Combined with the usage and behavioral sections, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents entity, facts, tier, type, domain, and derived_from. The description echoes concepts (authority tiers, logical dependencies) but adds no syntax, defaults, or value guidance beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (store) and resource (factual observations under an entity in a knowledge graph) and explicitly distinguishes itself from the forget/recall/context siblings. An agent can identify this as the write path for memory without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The WHEN TO USE block gives explicit positive triggers (new knowledge, preferences, decisions, verified facts) and two explicit exclusions routing to 'forget' (invalidation) and 'recall'/'context' (querying). Nothing about when to pick this over a sibling is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Sep 29, 2026
- First observedcontext
- First observedforget
- First observedrecall
- First observedremember

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored 2026-09-29 13:45 across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with explicit WHEN TO USE and DO NOT USE cross-references: remember stores, recall does keyword search, context traverses graph relationships, and forget invalidates/removes. An agent can easily tell them apart.

Naming Consistency4/5

All names are single lowercase words with no mixing of underscores or camelCase, which is consistent. However, 'context' is a noun while the other three (remember, recall, forget) are action verbs, a minor deviation from the otherwise consistent action-oriented pattern.

Tool Count5/5

The 4 tools are perfectly scoped for a knowledge graph memory server, covering the core operations of store, search, graph traversal, and invalidation without redundancy. Each tool earns its place.

Completeness5/5

The surface covers the full lifecycle: remember handles create and update (with contradiction detection and authority tiers), recall and context cover different read patterns, and forget handles soft or hard deletion with cascading invalidation. No obvious gaps for the stated memory domain.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

agentbay-mcp AOAuth
io.github.thomasjumper
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Knowledge & Memory Autonomous Agents Agent Orchestration
21
AiAkiv Memory AOAuth
com.aiakiv
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Knowledge & Memory Autonomous Agents
212
Penfield Memory AOAuth
io.github.penfieldlabs
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Knowledge & Memory RAG Systems Vector Databases
1726
Ace Memory BOAuth
io.github.rudedoggg
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Knowledge & Memory RAG Systems Autonomous Agents
4

Related MCP Servers

alaya
Databases Knowledge & Memory
SecurityRonin
A
license
Not graded
quality
C
maintenance
A local memory engine for AI agents. Stores conversation episodes, consolidates knowledge through a neuroscience-inspired lifecycle, and builds a personal knowledge graph — all in a local SQLite database.
Updated 2 months ago (2026-07-16 15:44 UTC)
17
MIT
Graph-Memory
Knowledge & Memory RAG Systems
stevepridemore
A
license
A
quality
C
maintenance
Self-hosted personal knowledge graph for Claude that persists across sessions, devices, and tools. Built on Neo4j with local semantic embeddings; OAuth 2.1 lets Claude Code, Claude Desktop, and claude.ai web all hit the same graph.
Updated 4 months ago (2026-05-17 20:03 UTC)
23
45 npm
2
MIT
mcp_sqlite_memory_bank
Knowledge & Memory Databases Search
robertmeisner
A
license
Not graded
quality
C
maintenance
Dynamic SQLite memory bank with semantic search, table management, and knowledge graphs for LLM agents.
Updated a year ago (2025-06-30 19:49 UTC)
2
MIT
rekal
Knowledge & Memory Autonomous Agents
janbjorge
A
license
Not graded
quality
A
maintenance
Provides long-term memory for LLMs via local SQLite storage with hybrid search (BM25, vectors, recency decay), enabling AI coding agents to persist and recall memories across sessions without cloud or API keys.
Updated a month ago (2026-08-26 07:07 UTC)
53
MIT

Technical Summary

⚡ Quickstart & IDE Setup

Installation Options

Option A: Universal One-Liner (Recommended)

Option B: GitHub Releases (Direct Tarball — Zero Login Required)

Option C: JSR (TypeScript / Deno / Bun / Node)

Option D: GitHub Packages (npm.pkg.github.com)

Option E: Build from Source

MCP Client Configurations

Claude Desktop (claude_desktop_config.json)

Cursor (.cursor/mcp.json)

Google Antigravity IDE (mcp_config.json)

Windsurf (mcp_config.json)

VS Code (Roo Code / Cline / Continue)

30-Second Verification

📑 Table of Contents

The Problem with Existing Agent Memory

1. The "LLM-in-LLM" Antipattern

2. State Invalidation Failure in Vector Databases

3. Opaque Storage Lock-in

Architectural Comparison: MCP Memory Ecosystem

Core Systems Deep Dive

1. Truth Maintenance System (TMS)

Authority Tiers

Mathematical Decay Scoring

Cascading Invalidation DAG

Pre-Insertion Contradiction Detection

2. Dual-Write Storage: Markdown-as-Truth

Sample Entity File (.amneshia/knowledge/backend/database.md):

3. Tool Surface & JSON-RPC Schemas

remember

recall

forget

context

3D Web Dashboard (Port 3457)

🌌 3D Neural Universe View

🔍 Memory Inspector & Truth Maintenance View

Launching the Dashboard

Agent System Rules & Prompt Presets

CLI Reference

Verified Test Suite

Design Non-Goals & Architectural Boundaries

Contributing & Community

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Option D: GitHub Packages (`npm.pkg.github.com`)

Claude Desktop (`claude_desktop_config.json`)

Cursor (`.cursor/mcp.json`)

Google Antigravity IDE (`mcp_config.json`)

Windsurf (`mcp_config.json`)

Sample Entity File (`.amneshia/knowledge/backend/database.md`):

`remember`

`recall`

`forget`

`context`