Amneshia

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

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

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

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

amneshia update           # Perform seamless in-place upgrade
amneshia update --check   # Check for updates without installing

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

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

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

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

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

# 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

---
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

# Ingest local media and attach facts into Amneshia CAS
amneshia media remember ./architecture.png -e "Architecture Diagram" -f "Microservices visual topology"

# List stored media assets with SHA-256 digests and file sizes
amneshia media list

# Purge unreferenced orphan media blobs
amneshia media prune

# Precompute vector embeddings for all active observations
amneshia embed

# Hybrid semantic search with RRF scoring
amneshia search "token expiration and refresh logic"

# Activate merge driver globally in ~/.gitconfig (PC / Workstation)
amneshia cloud setup-driver --global

# Synchronize across devices in one command
amneshia cloud sync

# Check if a new release is available
amneshia update --check

# Upgrade Amneshia in-place to latest release
amneshia update

MCP Toolset (Core Profile)
├── remember        : Entity upsert, observation recording, contradiction checks
├── remember_media  : Ingest local image/audio/document into CAS storage and link to entity
├── recall          : Hybrid BM25 + dense vector semantic search with token budgeting
├── forget          : Soft/hard invalidation with dependency cascade
├── context         : GraphRAG multi-hop relational traversal
├── status          : Inspect graph summary stats, node health, and cloud sync state
├── reindex         : Rebuild SQLite FTS5 index from Markdown-as-Truth files
└── sync            : Bidirectional Git cloud synchronization (pull / push / sync)

{
  "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"]
  }
}

{
  "name": "remember_media",
  "arguments": {
    "file_path": "/path/to/architecture-diagram.png",
    "entity": "Authentication",
    "facts": ["Architecture visual spec showing JWT authentication flow"],
    "domain": "architecture",
    "tier": "contextual"
  }
}

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

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

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

{
  "name": "status",
  "arguments": {}
}

{
  "name": "reindex",
  "arguments": {}
}

{
  "name": "sync",
  "arguments": {
    "action": "sync",
    "message": "sync: update memory from agent session"
  }
}

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

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

# Long-Term Memory Directives (Amneshia v3 Engine)

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

## 1. Pre-Flight Engine Update & Retrieval (Start of Every Session)
- **Check for Amneshia Updates:** At the start of a new conversation or if it has been a while since your last chat, always verify if the Amneshia engine needs an update (e.g., via `npm update -g @sabilmurti/amneshia` or `git pull` & `npm run build` if running from source) so you don't write code against an outdated memory engine from another device.
- **Mandatory Recall:** Before writing code, planning refactors, or suggesting libraries, ALWAYS query Amneshia:
  `recall({ query: "<topic/keyword>", token_budget: 1000 })` or inspect project context via `context({ domain: "<domain>" })`.
- **Hybrid Semantic Search:** Amneshia v3.1 leverages Reciprocal Rank Fusion (RRF) combining SQLite FTS5 BM25 lexical ranking with dense vector cosine similarity (via local ONNX `all-MiniLM-L6-v2`). You can query abstract concepts, symptoms, or architectural behaviors without needing exact keyword matches.
- **Never Guess Conventions:** Verify past architectural decisions, repository quirks, coding styles, and active credentials before scaffolding.

## 2. In-Flight Execution & Authority Tiers
- **Authority Levels:** Amneshia v3 enforces 4 strict authority tiers:
  - `invariant`: Immutable truths, user constraints, security rules, and permanent architectural decisions (never decays).
  - `architectural`: Framework choices, core database schemas, and API contracts (365 days retention).
  - `contextual`: Working conventions, active configurations, and environment state (90 days retention, default for agent observations).
  - `ephemeral`: Scratchpad notes, temporary debug logs, and short-lived session context (7 days TTL).
- **No Overwriting Invariants:** As an agent, your writes default to `contextual` authority. Never try to supersede or contradict user-defined invariant 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:**
  ```json
  {
    "name": "remember",
    "arguments": {
      "entity": "Web Dashboard Architecture",
      "facts": [
        "[Context & Rationale] Dashboard port changed to 3457 to prevent conflicts with Vite default 5173.",
        "[Technical Implementation] Modified src/server.ts and src/index.ts to pass stdio: false on serve subcommand.",
        "[Operational Parameters] Web Dashboard runs on http://localhost:3457. CLI: amneshia serve -p 3457.",
        "[Verification & Test Outcomes] Verified with curl /api/stats (200 OK) and 60/60 vitest assertions passing.",
        "[Architectural Guardrails & Gotchas] Stdio mode must be false when spawning daemon to avoid terminal SIGTTOU suspension."
      ],
      "tier": "architectural",
      "domain": "project:amneshia"
    }
  }
  ```

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

## 5. Dual-Write Transparency & Cloud Sync
- All stored memories are dual-written to `.amneshia/knowledge/{domain}/{entity}.md`. You may inspect or commit these files directly with git.
- **Pre-Flight Cloud Sync (Cross-Device):** At the start of a new conversation or if it has been a while since your last interaction, ALWAYS ensure memory is up-to-date with other devices. You can invoke the native MCP tool `sync({ action: "sync" })` (or terminal CLI `amneshia cloud sync`).
- **Memory Health Inspection:** Call `status({})` to verify node counts, authority tier distribution, active contradictions, and cloud Git remote status.

## 6. Smart 3-Way Git Merge Driver (Zero Conflict Markers)
- **Multi-Device Synchronization:** When synchronizing memory across machines (e.g. Workstation PC $\leftrightarrow$ Laptop $\leftrightarrow$ Mobile Termux), activate the custom merge driver:
  `amneshia cloud setup-driver` (or `amneshia cloud setup-driver -g` globally on PC).
- **Deterministic Reconciliation:** Never manually resolve raw merge conflicts (`<<<<<<< HEAD`) in `.amneshia/knowledge/*.md`. The driver semantically reconciles YAML frontmatter, deduplicates observation UUIDs and contents, preserves highest authority tiers, and unions directional relations mathematically.

## 7. Vector Index Maintenance
- **Local ONNX Ingestion:** After large Markdown imports or initial repository adoption, ensure 100% semantic coverage by executing:
  `amneshia embed`
- Memory embeddings run 100% offline via local ONNX with sub-millisecond SQLite BLOB lookups.

## 8. Content-Addressable Media Memory (CAS)
- **Media Ingestion:** If a task involves generating, receiving, or analyzing media (images, diagrams, binary files), ALWAYS ingest the file into Amneshia's CAS storage via `amneshia media remember <filepath> -e "<entity>"`.
- **Immutable Storage:** Media assets are deduplicated by SHA-256 and linked directly to entity facts. Never attempt to store raw base64 strings or absolute local paths inside standard text observations.

## 9. Disaster Recovery & SQLite Reindexing (`reindex`)
- **When to Reindex:** Invoke the MCP tool `reindex({})` (or CLI `amneshia reindex`) when:
  1. Knowledge markdown files have been manually edited, created, or deleted outside the active session.
  2. A Git pull/merge brought in external markdown updates without automatic index rebuilding.
  3. FTS5 full-text search indexes or SQLite cache become corrupted or desynchronized from Markdown-as-Truth files.
- **Strict Guardrail:** NEVER call `reindex()` repeatedly on routine conversation turns. Amneshia handles real-time dual-write updates automatically; reserve `reindex()` strictly for initial imports, post-git pulls, or disaster recovery.

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

# Scaffold local repo and automatically adopt memories from global ~/.amneshia
amneshia init -d backend          # Adopt specific domain
amneshia init -a                  # Adopt all global memories

# Adopt / cherry-pick global memories into current project with deduplication
amneshia adopt -d project:core    # Filter by domain
amneshia adopt -e "Auth Module"   # Filter by specific entities
amneshia adopt --dry-run          # Preview migration without modifying target
amneshia adopt --move             # Move memories (delete from source after copying)

# Universal Memory Export (SQLite, Markdown bundle, or JSON)
amneshia export memory.db -f sqlite                # Full standalone SQLite database
amneshia export ./md-export -f markdown            # Markdown directory with index.md catalog
amneshia export memory.json -f json -d backend     # JSON dump filtered by domain
amneshia export dump.json -f json -t invariant     # Filter by authority tier
amneshia export search.json -f json -q "jwt token" # Filter by FTS5 BM25 search query

# Git-Native Cloud Synchronization (Self-Hostable across all devices)
amneshia cloud setup git@github.com:user/my-memory.git  # Link private Git repository
amneshia cloud status                                   # Inspect sync health & uncommitted facts
amneshia cloud pull                                     # Pull remote updates & reindex SQLite FTS5
amneshia cloud push -m "Synced memory"                  # Commit & push local knowledge
# Smart 3-Way Git Merge Driver (Zero conflict markers across PC and mobile)
amneshia cloud setup-driver              # Activate driver in knowledge repo (.gitattributes)
amneshia cloud setup-driver --global     # Activate driver globally in ~/.gitconfig (PC / Workstation)

# Local ONNX Hybrid Semantic Search (FTS5 BM25 + Vector Cosine Similarity via RRF)
amneshia embed                           # Precompute vector embeddings for active observations
amneshia embed --force                   # Recompute all vector embeddings from scratch
amneshia search "Android memory limits"  # Hybrid semantic search with Reciprocal Rank Fusion

# Deterministic Media Memory Engine (Content-Addressable Storage / CAS)
amneshia media list                           # Inspect stored media assets across the graph
amneshia media remember ./diagram.png -e "Architecture" -f "System design spec" # Ingest media into CAS
amneshia media prune                          # Purge unreferenced orphan media blobs

# Self-Updater (Automated in-place upgrade from GitHub Releases / JSR)
amneshia update --check                  # Check for updates without installing
amneshia update                          # Perform seamless in-place upgrade
amneshia update --force                  # Force re-installation / rebuild

# 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

$ npm test

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

 Test Files  10 passed (10)
      Tests  49 passed (49)
   Duration  2.34s