diff --git a/README.md b/README.md
index 9e47212..a93a21b 100644
--- a/README.md
+++ b/README.md
@@ -1,123 +1,393 @@
+
+ 
Engram
+
+ The Personal Memory Kernel for AI Agents
+
+
- Memory layer for AI agents with biologically-inspired forgetting.
+ A user-owned memory store that any agent can plug into to become instantly personalized.
+ Agents read via scoped retrieval. Writes land in staging until you approve.
+
+ 
+ 
+ 
+ 
+
- Quick Start ·
- What is Engram ·
- Features ·
- Integrations ·
- API
+ Quick Start ·
+ Why Engram ·
+ Architecture ·
+ Integrations ·
+ API & SDK ·
+ Changelog
---
+> **100% free, forever.** No Pro tier, no usage limits, no license keys. Bring your own API key (Gemini, OpenAI, or Ollama). Everything runs locally by default.
+
+---
+
+## Why Engram
+
+Every AI agent you use starts with amnesia. Your coding assistant forgets your preferences between sessions. Your planning agent has no idea what your research agent discovered yesterday. You end up re-explaining context that should already be known.
+
+**Engram fixes this.** It's a Personal Memory Kernel (PMK) — a single memory store that sits between you and all your agents. Any agent can plug in via MCP or REST to become instantly personalized, without you having to repeat yourself.
+
+But unlike "store everything forever" approaches, Engram treats agents as **untrusted writers**. Writes land in staging. You control what sticks. And memories that stop being useful fade away naturally — just like biological memory.
+
+| Capability | Other Memory Layers | **Engram** |
+|:-----------|:--------------------|:-----------|
+| Bio-inspired forgetting | No | **Ebbinghaus decay curve** |
+| Untrusted agent writes | Store directly | **Staging + verification + conflict stash** |
+| Episodic narrative memory | No | **CAST scenes (time/place/topic)** |
+| Multi-modal encoding | Rare | **5 retrieval paths (EchoMem)** |
+| Cross-agent memory sharing | Per-agent silos | **Scoped retrieval with masking** |
+| Knowledge graph | Sometimes | **Entity extraction + linking** |
+| Reference-aware decay | No | **If other agents use it, don't delete it** |
+| Hybrid search | Vector only | **Semantic + keyword + episodic** |
+| Storage efficiency | Store everything | **~45% less** |
+| MCP + REST | One or the other | **Both, plug-and-play** |
+| Local-first | Cloud-required | **127.0.0.1:8100 by default** |
+
+---
+
## Quick Start
```bash
-pip install -e ".[all]" # 1. Install
-export GEMINI_API_KEY="..." # 2. Set API key (or OPENAI_API_KEY)
-engram install # 3. Configure Claude Code, Cursor, Codex
+pip install -e ".[all]" # 1. Install
+export GEMINI_API_KEY="your-key" # 2. Set one API key (or OPENAI_API_KEY, or OLLAMA_HOST)
+engram install # 3. Auto-configure Claude Code, Cursor, Codex
```
-Done. Your agents now have persistent memory.
+Restart your agent. Done — it now has persistent memory across sessions.
+
+**Or with Docker:**
+
+```bash
+docker compose up -d # API at http://localhost:8100
+```
---
-## What is Engram
+## Architecture
-Engram is a memory layer for AI agents. It stores knowledge, forgets what doesn't matter, and strengthens what does — using mechanisms inspired by how biological memory works. It plugs into Claude Code, Cursor, and Codex via MCP, or into any application via REST API and Python SDK.
+Engram is a **Personal Memory Kernel** — not just a vector store with an API. It has opinions about how memory should work:
-**100% free, forever. Bring your own API key (Gemini, OpenAI, or Ollama).**
+1. **Agents are untrusted writers.** Every write is a proposal that lands in staging. Trusted agents can auto-merge; untrusted ones wait for approval.
+2. **Memory has a lifecycle.** New memories start in short-term (SML), get promoted to long-term (LML) through repeated access, and fade away through Ebbinghaus decay if unused.
+3. **Scoping is mandatory.** Every memory is scoped by user. Agents see only what they're allowed to — everything else gets the "all but mask" treatment (structure visible, details redacted).
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Agent Orchestrator │
+│ (Claude Code / Cursor / Codex / Custom) │
+└─────────────────────────┬───────────────────────────────────────┘
+ │
+ ┌───────────┴───────────┐
+ │ │
+ ▼ ▼
+ ┌──────────┐ ┌──────────┐
+ │ MCP │ │ REST │
+ │ Server │ │ API │
+ └────┬─────┘ └────┬─────┘
+ └───────────┬──────────┘
+ ▼
+ ┌────────────────────────────────────┐
+ │ Policy Gateway │
+ │ Scopes · Masking · Quotas · │
+ │ Capability Tokens · Trust Score │
+ └────────────────┬───────────────────┘
+ │
+ ┌──────────┴──────────┐
+ ▼ ▼
+ ┌──────────────────┐ ┌──────────────────┐
+ │ Retrieval Engine │ │ Ingestion Pipeline│
+ │ ┌─────────────┐ │ │ │
+ │ │Semantic │ │ │ Text → Views │
+ │ │(hybrid+graph│ │ │ Views → Scenes │
+ │ │+categories) │ │ │ Scenes → LML │
+ │ ├─────────────┤ │ │ │
+ │ │Episodic │ │ └────────┬─────────┘
+ │ │(CAST scenes)│ │ │
+ │ └─────────────┘ │ ▼
+ │ │ ┌──────────────────┐
+ │ Intersection │ │Write Verification│
+ │ Promotion: │ │ │
+ │ match in both → │ │ Invariant checks │
+ │ boost score │ │ Conflict → stash │
+ └──────────────────┘ │ Trust scoring │
+ └────────┬─────────┘
+ │
+ ┌───────────────────┼───────────────────┐
+ ▼ ▼ ▼
+ ┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
+ │ Staging (SML) │ │ Long-Term │ │ Indexes │
+ │ Proposals+Diffs │ │ Store (LML) │ │ Vector + Graph │
+ │ Conflict Stash │ │ Canonical │ │ + Episodic │
+ └──────────────────┘ └──────────────┘ └──────────────────┘
+ │ │ │
+ └───────────────────┼───────────────────┘
+ ▼
+ ┌──────────────────┐
+ │ FadeMem GC │
+ │ Ref-aware decay │
+ │ If other agents │
+ │ use it → keep │
+ └──────────────────┘
+```
+
+### The Memory Stack
+
+Engram combines four bio-inspired memory systems, each handling a different aspect of how humans actually remember:
+
+#### FadeMem — Decay & Consolidation
+
+Memories fade based on time and access patterns, following the Ebbinghaus forgetting curve. Frequently accessed memories get promoted from short-term (SML) to long-term (LML). Unused memories weaken and eventually get forgotten. **Reference-aware:** if other agents still reference a memory, it won't be garbage collected — even if the original agent stopped using it.
+
+```
+New Memory → Short-term (SML)
+ │
+ │ Accessed frequently?
+ ▼
+ ┌──────────┐
+ No ← │ Decay │ → Yes
+ └──────────┘
+ │ │
+ ▼ ▼
+ Forgotten Promoted to Long-term (LML)
+```
+
+#### EchoMem — Multi-Modal Encoding
+
+Each memory is encoded through multiple retrieval paths — keywords, paraphrases, implications, and question forms. This creates 5x the retrieval surface area compared to single-embedding approaches. Important memories get deeper processing (1.6x strength multiplier).
+
+```
+Input: "User prefers TypeScript over JavaScript"
+ ↓
+ raw: "User prefers TypeScript over JavaScript"
+ paraphrase: "TypeScript is the user's preferred language"
+ keywords: ["typescript", "javascript", "preference"]
+ implications: ["values type safety", "modern tooling"]
+ question: "What language does the user prefer?"
+```
+
+#### CategoryMem — Dynamic Organization
+
+Categories aren't predefined — they emerge from content and evolve over time. As new memories arrive, the category tree grows, splits, and merges. Categories themselves decay when unused, keeping the taxonomy clean.
+
+#### CAST Scenes — Episodic Narrative Memory
+
+Inspired by the Contextual Associative Scene Theory of memory, Engram clusters interactions into **scenes** defined by three dimensions: time, place, and topic. Each scene has characters, a synopsis, and links to the semantic memories extracted from it.
+
+```
+Scene: "Engram v2 architecture session"
+ Time: 2026-02-09 12:00–12:25
+ Place: repo:Engram (digital)
+ Characters: [self, collaborator]
+ Synopsis: "Designed staged writes and scoped retrieval..."
+ Views: [view_1, view_2, view_3]
+ Memories: [mem_1, mem_2] ← semantic facts extracted
+```
---
-## Key Features
+### Key Flows
-- **FadeMem** — Dual-layer memory (short-term / long-term) with Ebbinghaus decay. Memories fade when unused, strengthen when accessed, and promote automatically.
-- **EchoMem** — Multi-modal encoding creates multiple retrieval paths (keywords, paraphrases, implications, question forms) for better recall.
-- **CategoryMem** — Dynamic hierarchical categories emerge from content and evolve over time. Categories decay too.
-- **Scenes** — Episodic memory groups interactions into narrative scenes with time gap and topic shift detection.
-- **Profiles** — Character profile extraction tracks entities across conversations.
-- **Knowledge Graph** — Entity extraction and linking for relationship reasoning across memories.
-- **MCP Server** — Native Model Context Protocol integration for Claude Code, Cursor, and Codex.
-- **REST API** — Language-agnostic HTTP API with session tokens, staged writes, and namespace scoping.
-- **Hybrid Search** — Combines semantic similarity with keyword matching for better precision.
-- **Multi-Agent** — Scoped by user and agent. Agents share knowledge or isolate it.
-- **~45% Storage Reduction** — Compared to store-everything approaches.
+#### Read: Query → Context Packet
+
+```
+Agent calls search_memory or POST /v1/search
+ → Policy Gateway enforces scope, quotas, masking
+ → Dual retrieval: semantic index + episodic index (parallel)
+ → Intersection promotion: results matching in both get boosted
+ → Returns Context Packet (token-budgeted, with scene citations)
+```
+
+The dual retrieval approach reduces "similar but wrong time/place" errors. If a memory appears in both semantic search and the relevant episodic scene, it gets a confidence boost.
+
+#### Write: Agent Proposal → Staging
+
+```
+Agent calls propose_write or POST /v1/memories
+ → Lands in Staging SML as a Proposal Commit
+ → Provenance recorded (agent, time, scope, trust score)
+ → Verification runs:
+ • Invariant contradiction check → stash if conflict
+ • Duplication detection
+ • PII risk detection → require manual approval if high
+ → High-trust agents: auto-merge
+ → Others: wait for user approval or daily digest
+```
+
+#### "All But Mask" Policy
+
+When an agent queries data outside its scope, it sees structure but not details:
+
+```json
+{
+ "type": "private_event",
+ "time": "2026-02-10T17:00:00Z",
+ "importance": "high",
+ "details": "[REDACTED]"
+}
+```
+
+Agents can still operate (scheduling, planning) without seeing secrets.
---
-## Installation
+## Integrations
+
+Engram is plug-and-play. Run `engram install` and it auto-configures everything:
-### pip (recommended)
+### Claude Code (MCP + Plugin)
```bash
-pip install -e ".[all]"
+engram install # Writes MCP config to ~/.claude.json
```
-### Docker
+**MCP tools** give Claude reactive memory — it stores and retrieves when you ask.
+
+The optional **Claude Code plugin** makes memory **proactive** — relevant context is injected automatically before Claude sees your message:
```bash
-docker compose up -d
-# API available at http://localhost:8100
+# Inside Claude Code:
+/plugin install engram-memory --path ~/.engram/claude-plugin
```
-### From source
+What the plugin adds:
-```bash
-git clone https://github.com/Ashish-dwi99/Engram.git
-cd Engram
-python3 -m venv .venv && source .venv/bin/activate
-pip install -e ".[all]"
+| Component | What it does |
+|:----------|:-------------|
+| **UserPromptSubmit hook** | Before each reply, queries Engram and injects matching memories into context. Stdlib-only, no extra deps. Under 2s latency. |
+| `/engram:remember ` | Save a fact or preference on the spot |
+| `/engram:search ` | Search memories by topic |
+| `/engram:forget ` | Delete a memory (confirms before removing) |
+| `/engram:status` | Show memory-store stats at a glance |
+| **Skill** | Standing instructions telling Claude when to save, search, and surface memories |
+
+**Without plugin** — Claude reacts to explicit requests:
+```
+You: Remember that I prefer TypeScript
+Claude: [calls remember tool] Done.
+```
+
+**With plugin** — memory is proactive and invisible:
```
+--- Session A ---
+You: /engram:remember I prefer TypeScript for all new projects
+
+--- Session B (new conversation, no history) ---
+You: What stack should I use for the new API?
+[Hook injects "TypeScript preference" before Claude sees the message]
+Claude: Based on your preferences, I'd recommend TypeScript...
+```
+
+### Cursor
+
+`engram install` writes MCP config to `~/.cursor/mcp.json`. Restart Cursor to load.
+
+### OpenAI Codex
+
+`engram install` writes MCP config to `~/.codex/config.toml`. Restart Codex to load.
+
+### OpenClaw
+
+`engram install` deploys the Engram skill to OpenClaw's skills directory.
+
+### Any Agent Runtime
-Set one API key:
+Any tool-calling agent can connect via REST:
```bash
-export GEMINI_API_KEY="your-key" # Gemini (default)
-# or OPENAI_API_KEY for OpenAI
-# or OLLAMA_HOST for local Ollama (no key needed)
+engram-api # Starts on http://127.0.0.1:8100
```
---
-## Usage
+## MCP Tools
-### MCP Tools
-
-After running `engram install`, your agent gets 14 MCP tools including:
+Once configured, your agent has access to these tools:
| Tool | Description |
-|------|-------------|
-| `add_memory` | Store a new memory |
-| `search_memory` | Semantic + keyword search |
-| `get_all_memories` | List stored memories |
-| `update_memory` / `delete_memory` | Modify or remove |
-| `apply_memory_decay` | Run forgetting algorithm |
-| `engram_context` | Load session digest from prior sessions |
-| `remember` | Quick-save a fact (no LLM extraction) |
-| `search_scenes` / `get_scene` | Episodic scene retrieval |
+|:-----|:------------|
+| `add_memory` | Store a new memory (lands in staging by default) |
+| `search_memory` | Semantic + keyword + episodic search |
+| `get_all_memories` | List all stored memories for a user |
+| `get_memory` | Get a specific memory by ID |
+| `update_memory` | Update memory content |
+| `delete_memory` | Remove a memory |
+| `get_memory_stats` | Storage statistics and health |
+| `apply_memory_decay` | Run the forgetting algorithm |
+| `engram_context` | Session-start digest — load top memories from prior sessions |
+| `remember` | Quick-save a fact (no LLM extraction, stores directly) |
+| `propose_write` | Create a staged write proposal (default safe path) |
+| `list_pending_commits` | Inspect staged write queue |
+| `resolve_conflict` | Resolve invariant conflicts (accept proposed or keep existing) |
+| `search_scenes` / `get_scene` | Episodic CAST scene retrieval with masking policy |
-### CLI
+---
+
+## API & SDK
+
+### REST API
```bash
-engram add "User prefers Python" -u user123
-engram search "programming" -u user123
-engram list -u user123
-engram stats
-engram status # Version, config paths, DB stats
-engram serve # Start REST API
-engram decay # Apply forgetting
-engram export -o memories.json
-engram import memories.json
+engram-api # http://127.0.0.1:8100
+ # Interactive docs at /docs
+```
+
+```bash
+# 1. Create a capability session token
+curl -X POST http://localhost:8100/v1/sessions \
+ -H "Content-Type: application/json" \
+ -d '{
+ "user_id": "u123",
+ "agent_id": "planner",
+ "allowed_confidentiality_scopes": ["work", "personal"],
+ "capabilities": ["search", "propose_write", "read_scene"],
+ "ttl_minutes": 1440
+ }'
+
+# 2. Propose a write (default: staging)
+curl -X POST http://localhost:8100/v1/memories \
+ -H "Authorization: Bearer " \
+ -H "Content-Type: application/json" \
+ -d '{"content": "User prefers dark mode", "user_id": "u123", "mode": "staging"}'
+
+# 3. Search (returns context packet with scene citations)
+curl -X POST http://localhost:8100/v1/search \
+ -H "Authorization: Bearer " \
+ -H "Content-Type: application/json" \
+ -d '{"query": "UI preferences", "user_id": "u123"}'
+
+# 4. Review staged commits
+curl "http://localhost:8100/v1/staging/commits?user_id=u123&status=PENDING"
+curl -X POST http://localhost:8100/v1/staging/commits//approve
+
+# 5. Episodic scene search
+curl -X POST http://localhost:8100/v1/scenes/search \
+ -H "Content-Type: application/json" \
+ -d '{"query": "architecture discussion", "user_id": "u123"}'
+
+# 6. Namespace & trust management
+curl -X POST http://localhost:8100/v1/namespaces \
+ -d '{"user_id": "u123", "namespace": "workbench"}'
+curl "http://localhost:8100/v1/trust?user_id=u123&agent_id=planner"
+
+# 7. Sleep-cycle maintenance
+curl -X POST http://localhost:8100/v1/sleep/run \
+ -d '{"user_id": "u123", "apply_decay": true, "cleanup_stale_refs": true}'
```
### Python SDK
@@ -126,102 +396,277 @@ engram import memories.json
from engram import Engram
memory = Engram()
-memory.add("User prefers Python", user_id="u123")
+
+# Add a memory
+memory.add("User prefers Python over JavaScript", user_id="u123")
+
+# Search with dual retrieval
results = memory.search("programming preferences", user_id="u123")
+
+# Cross-agent knowledge sharing
+memory.add(
+ "The API rate limit is 100 req/min",
+ user_id="team_alpha",
+ agent_id="researcher",
+ categories=["technical", "api"]
+)
+
+# Another agent finds it
+results = memory.search("rate limits", user_id="team_alpha")
```
-Full interface with `Memory` class:
+**Full Memory interface:**
```python
from engram import Memory
memory = Memory()
+
+# Lifecycle
memory.add(content, user_id, agent_id=None, categories=None, metadata=None)
-memory.search(query, user_id, limit=10)
memory.get(memory_id)
memory.update(memory_id, content)
memory.delete(memory_id)
-memory.promote(memory_id) # SML -> LML
-memory.history(memory_id)
-memory.get_related_memories(memory_id) # Knowledge graph
+
+# Search
+memory.search(query, user_id, agent_id=None, limit=10, categories=None)
+memory.get_all(user_id, agent_id=None, layer=None, limit=100)
+
+# Memory management
+memory.promote(memory_id) # SML → LML
+memory.demote(memory_id) # LML → SML
+memory.fuse(memory_ids) # Combine related memories
+memory.decay(user_id=None) # Apply forgetting
+memory.history(memory_id) # Access history
+
+# Knowledge graph
+memory.get_related_memories(memory_id) # Graph traversal
+memory.get_memory_entities(memory_id) # Extracted entities
+memory.get_entity_memories(entity_name) # All memories with entity
+memory.get_memory_graph(memory_id) # Visualization data
+
+# Categories
+memory.get_category_tree()
+memory.search_by_category(category_id)
+memory.stats(user_id=None, agent_id=None)
```
-### REST API
+**Async support:**
-```bash
-engram-api # Starts on http://127.0.0.1:8100
+```python
+from engram.memory.async_memory import AsyncMemory
+
+async with AsyncMemory() as memory:
+ await memory.add("User prefers Python", user_id="u1")
+ results = await memory.search("programming", user_id="u1")
```
+### CLI
+
```bash
-# Add memory
-curl -X POST http://localhost:8100/v1/memories \
- -H "Content-Type: application/json" \
- -d '{"content": "User prefers dark mode", "user_id": "u123"}'
+engram install # Auto-configure all integrations
+engram status # Version, config paths, DB stats
+engram serve # Start REST API server
+
+engram add "User prefers Python" # Add a memory
+engram search "preferences" # Search
+engram list --layer lml # List long-term memories
+engram stats # Memory statistics
+engram decay # Apply forgetting
+engram categories # List categories
+
+engram export -o memories.json # Export
+engram import memories.json # Import (Engram or Mem0 format)
+```
-# Search
-curl -X POST http://localhost:8100/v1/search \
- -H "Content-Type: application/json" \
- -d '{"query": "UI preferences", "user_id": "u123"}'
+---
+
+## Configuration
-# Stats
-curl "http://localhost:8100/v1/stats?user_id=u123"
+```bash
+# LLM & Embeddings (choose one)
+export GEMINI_API_KEY="your-key" # Gemini (default)
+export OPENAI_API_KEY="your-key" # OpenAI
+export OLLAMA_HOST="http://localhost:11434" # Ollama (local, no key)
+
+# v2 features (all enabled by default)
+export ENGRAM_V2_POLICY_GATEWAY="true" # Token + scope enforcement
+export ENGRAM_V2_STAGING_WRITES="true" # Writes land in staging
+export ENGRAM_V2_DUAL_RETRIEVAL="true" # Semantic + episodic search
+export ENGRAM_V2_REF_AWARE_DECAY="true" # Preserve referenced memories
+export ENGRAM_V2_TRUST_AUTOMERGE="true" # Auto-approve for trusted agents
+export ENGRAM_V2_AUTO_MERGE_TRUST_THRESHOLD="0.85" # Trust threshold for auto-merge
```
-Full API docs at http://localhost:8100/docs
+**Python config:**
+
+```python
+from engram.configs.base import MemoryConfig, FadeMemConfig, EchoMemConfig, CategoryMemConfig
+
+config = MemoryConfig(
+ fadem=FadeMemConfig(
+ enable_forgetting=True,
+ sml_decay_rate=0.15,
+ lml_decay_rate=0.02,
+ promotion_access_threshold=3,
+ forgetting_threshold=0.1,
+ ),
+ echo=EchoMemConfig(
+ enable_echo=True,
+ auto_depth=True,
+ deep_multiplier=1.6,
+ ),
+ category=CategoryMemConfig(
+ enable_categories=True,
+ auto_categorize=True,
+ enable_category_decay=True,
+ max_category_depth=3,
+ ),
+)
+```
---
-## Integrations
+## Multi-Agent Memory
-### Claude Code
+Engram is designed for agent orchestrators. Every memory is scoped by `user_id` and optionally `agent_id`:
-```bash
-engram install # Writes MCP config to ~/.claude.json
-```
+```python
+# Research agent stores knowledge
+memory.add("OAuth 2.0 with JWT tokens",
+ user_id="project_123", agent_id="researcher")
-The optional **Claude Code plugin** adds proactive memory injection (relevant context is loaded before each reply), slash commands (`/engram:remember`, `/engram:search`, `/engram:status`), and standing instructions.
+# Implementation agent searches shared knowledge
+results = memory.search("authentication", user_id="project_123")
+# → Finds researcher's discovery
-```bash
-# Activate plugin inside Claude Code:
-/plugin install engram-memory --path ~/.engram/claude-plugin
+# Review agent adds findings
+memory.add("Security review passed",
+ user_id="project_123", agent_id="reviewer")
```
-Requires `engram-api` running for the proactive hook.
+**Agent trust scoring** determines write permissions:
+- High-trust agents (>0.85): proposals auto-merge
+- Medium-trust: queued for daily digest review
+- Low-trust: require explicit approval
-### Cursor
+---
-`engram install` writes MCP config to `~/.cursor/mcp.json`. Restart Cursor to load.
+## Research
-### OpenAI Codex
+Engram is based on:
-`engram install` writes MCP config to `~/.codex/config.toml`. Restart Codex to load.
+> **FadeMem: Biologically-Inspired Forgetting for Efficient Agent Memory**
+> [arXiv:2601.18642](https://arxiv.org/abs/2601.18642)
-### OpenClaw
+| Metric | Result |
+|:-------|:-------|
+| Storage Reduction | ~45% |
+| Multi-hop Reasoning | +12% accuracy |
+| Retrieval Precision | +8% on LTI-Bench |
-`engram install` deploys the Engram skill to OpenClaw's skills directory.
+Biological inspirations: Ebbinghaus Forgetting Curve → exponential decay, Spaced Repetition → access boosts strength, Sleep Consolidation → SML → LML promotion, Production Effect → echo encoding, Elaborative Encoding → deeper processing = stronger memory.
---
-## Architecture
+## Docker
+```bash
+# Quick start
+docker compose up -d
+
+# Or build manually
+docker build -t engram .
+docker run -p 8100:8100 -v engram-data:/data \
+ -e GEMINI_API_KEY="your-key" engram
+```
+
+---
+
+## Manual Integration Setup
+
+
+Claude Code / Claude Desktop
+
+Add to `~/.claude.json` (CLI) or `claude_desktop_config.json` (Desktop):
+
+```json
+{
+ "mcpServers": {
+ "engram-memory": {
+ "command": "python",
+ "args": ["-m", "engram.mcp_server"],
+ "env": {
+ "GEMINI_API_KEY": "your-api-key"
+ }
+ }
+ }
+}
+```
+
+
+
+Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+ "mcpServers": {
+ "engram-memory": {
+ "command": "python",
+ "args": ["-m", "engram.mcp_server"],
+ "env": {
+ "GEMINI_API_KEY": "your-api-key"
+ }
+ }
+ }
+}
```
-Agent (Claude Code / Codex / Cursor / LangChain)
- │
- ▼
-┌─────────────────────────────────────────────┐
-│ Engram │
-│ │
-│ Knowledge Graph (entity linking) │
-│ CategoryMem (dynamic organization) │
-│ EchoMem (multi-modal encoding) │
-│ FadeMem (decay & consolidation) │
-│ │
-│ Embedder: Gemini / OpenAI / Ollama │
-│ Store: SQLite + in-memory vectors │
-└─────────────────────────────────────────────┘
+
+
+
+OpenAI Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.engram-memory]
+command = "python"
+args = ["-m", "engram.mcp_server"]
+
+[mcp_servers.engram-memory.env]
+GEMINI_API_KEY = "your-api-key"
```
+
+
+---
+
+## Troubleshooting
+
+
+Claude Code doesn't see the memory tools
+
+- Restart Claude Code after running `engram install`
+- Check that `~/.claude.json` has an `mcpServers.engram-memory` section
+- Verify your API key: `echo $GEMINI_API_KEY`
+
+
+
+The hook isn't injecting memories
+
+- Check that `engram-api` is running: `curl http://127.0.0.1:8100/health`
+- Verify the plugin is activated: run `/plugin` in Claude Code
+- Check script permissions: `ls -l ~/.engram/claude-plugin/engram-memory/hooks/prompt_context.py`
+
+
+
+API won't start (port in use)
-Memories flow through four layers: FadeMem manages lifecycle (decay, promotion, forgetting), EchoMem creates multiple encodings for better retrieval, CategoryMem organizes content into dynamic hierarchies, and the Knowledge Graph links entities across memories.
+- Check: `lsof -i :8100`
+- Kill the process: `kill `
+- Or use a different port: `ENGRAM_API_PORT=8200 engram-api`
+
---
@@ -243,5 +688,9 @@ MIT License — see [LICENSE](LICENSE) for details.
---
- Built for AI agents that need to remember what matters.
+ Your agents forget everything between sessions. Engram fixes that.
+
+ GitHub ·
+ Issues ·
+ Changelog