Agent Memory MCP

Multi-tier memory server for AI agents with a full neural-cortical architecture. Episodic, semantic, and procedural memory with hybrid search, knowledge graphs, dream consolidation, and 45+ MCP tools.

                   ╔══════════════════════════════════════════╗
                   ║         CORTICAL ARCHITECTURE           ║
                   ╚══════════════════════════════════════════╝
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
    ┌────┴────┐          ┌────┴────┐          ┌────┴────┐
    │  PFC    │          │  ACC    │          │  BG     │
    │Enhance  │◄─────────┤Strategy │          │ Optimize│
    │+strategy│  inj.    │Select   │          │Bottleneck│
    └─────────┘          └─────────┘          └─────────┘
         │                     │                     │
         └─────────────────────┼─────────────────────┘
                               │
                    ┌──────────┴──────────┐
                    │     Thalamus        │
                    │  Context-Aware      │
                    │  Dynamic Router     │
                    └──────────┬──────────┘
                               │
               ┌───────────────┼───────────────┐
               │               │               │
         ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐
         │  Optical  │  │   Touch   │  │  Audio-   │
         │  Visual   │  │Tool Obsrv │  │  Spatial  │
         │  Cortex   │  │Proficienc │  │  Map+Sound│
         └───────────┘  └───────────┘  └───────────┘
               │               │               │
               └───────────────┼───────────────┘
                               │
                    ┌──────────┴──────────┐
                    │     Columnar        │
                    │   Cortex Pool       │
                    │ 8 cols · 5 temps    │
                    │ 5 prompts · subspce │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    │     Limbic          │
                    │  Valence -1 to +1   │
                    │  Inhibit/Reinforce  │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    │     Broca           │
                    │  Persona-Aware      │
                    │  Output Reformulate │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    │  DMN Dream Engine   │
                    │ Consolidate · Prune │
                    │ Link · Promote      │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    │  Memory Tiers       │
                    │ Episodic · Semantic │
                    │ Procedural · KG     │
                    └─────────────────────┘

Architecture

Memory Tiers (3 + KG)

Tier	What It Stores	How It's Searched	Decay Half-Life
Episodic	Events, logs, sessions	FTS5 BM25 + LIKE fallback	7 days
Semantic	Facts, knowledge, concepts	FTS5 BM25 + LIKE fallback	90 days
Procedural	How-to, workflows, skills	FTS5 BM25 + LIKE fallback	365 days
Knowledge Graph	Entities + relations + behavioral rules	FTS5 + BFS traversal	None (explicit only)

Cortical Regions (8 Executive + 3 Sensory + 1 Consolidation)

Executive Layer

Region	MCP Tool	Function	Real Implementation
PFC (Prefrontal)	cortex_pfc_enhance	Cognitive scaffolding with strategy injection	ACC-selected strategy protocol injected into enhancement scaffold. 4 modes: base/enhanced/expert/genius.
ACC (Anterior Cingulate)	cortex_acc_strategy	Strategy switching (6 patterns)	Keyword-match detection for chain-of-thought, tree-of-thoughts, reflexion, constitutional, mixture-of-agents, self-rewarding.
BG (Basal Ganglia)	cortex_bg_optimize	Bottleneck detection, habit formation	Flags operations >5s. Tracks procedural memory access frequency.
OFC (Orbitofrontal)	cortex_ofc_persona	Personality adaptation, modulates 4 downstream targets	Sets system prompt, valuation bias, attention bias. Modulates PFC/Thalamus/Limbic/Broca. 4 personas.
Thalamus	cortex_thalamus_route	Attention gating, 6 routing targets	Keyword-based routing. Now also context-aware via engine_route.
Limbic	engine_limbic_evaluate	Affective valence (-1 to +1), behavior loop	Actually changes behavior: inhibits actions after 3 negative outcomes, reinforces after 3 positive outcomes.
Broca	cortex_broca_reformulate	Output reformulation per persona	Adds persona-specific instruction prefix to output.
Columnar	engine_columnar_process	Ensemble voting with real diversity	8 columns with 5 different temperatures (0.1-0.9), 5 distinct prompt framings (critical/creative/stepwise/expert/simplify), random 30-50% input subspaces. Confidence-weighted pooling.

Sensory Layer

Region	MCP Tool	Function	Integration
Optical	optical_perceive	Visual perception (8 modalities)	Browser, screenshots, OCR, PDF, HTML, SVG, design, camera. Extracts entities.
Touch	touch_observe_tool	Tool interaction observation	Every tool call logged → proficiency map. Success rates tracked over time.
Audio-Spatial	audio_spatial_hear/locate	Sound processing + spatial mapping	Speech, music, analysis + filesystem, network, container topology.

Consolidation Layer

System	MCP Tools	Function	Real Effect
DMN Dream Engine	dream_cycle, get_behavioral_rules, analyze_behavioral_patterns	3-phase consolidation (nap/deep/full)	Recall → analyze → reinforce good → inhibit bad → prune weak
DMN Consolidation	engine_consolidate	System state modification	Actually changes system: prunes weak entries, creates associative links across entities, promotes behavioral rules to higher importance, records consolidation events in KG.
Context Pressure	Built into engine	Auto-summarization at threshold	Tracks token usage against 128K ceiling. Triggers summarization at 70%, critical at 85%.
Tiered Memory	Built into engine	Hot/warm/cold classification	Composite score from access_count, recency, importance. Exponential decay: score * 0.95^days.

Engine Tools (Functional, No Labels)

These are the tools that actually do things — not renamed features, but real functional systems:

Tool	What It Actually Does
engine_consolidate	Prunes weak KG entries, links related entities via related_to relations, promotes frequently-accessed behavioral rules. Stores consolidation events.
engine_limbic_evaluate	Scores outcome -1 to +1. On 3rd negative: creates inhibit:* KG entity. On 3rd positive: creates best-practice:* KG entity. These entities can be read by the safety pipeline.
engine_route	Routes input based on live context: recent_failures >3 → ACC for strategy, workload >10 → BG for optimization, creative persona → OFC first.
engine_columnar_process	8 columns, each with unique temp (0.1-0.9) + unique prompt framing + random subspace mask (30-50%). Returns confidence-weighted consensus.
engine_oscillation_status	Real phase tracking with coherence gates. Auto-switches mode (fast/medium/slow) based on workload. Consolidation gate opens when coherence >0.85.
engine_creativity_diverge	Generates N approaches using diverse thinking styles (engineering, nature, philosophy, design, economics, quantum, craft, systems) pulled from KG domains.
engine_creativity_analog	Searches known analogy pairs + KG entities for structural cross-domain matches. Falls back to generative KG-based analogies.

Domain Knowledge Modules

7 domains auto-seeded on first server start (74 entities, 146 aliases):

🌳 Woodworking    → 12 entities: joinery, materials, tools, finishes
🌱 Gardening      → 10 entities: compost, pH, companion planting, permaculture
⚡ Electronics    → 11 entities: Ohm's law, transistors, op-amps, Arduino
💭 Philosophy     → 10 entities: Plato→Nietzsche, Stoicism, Existentialism
📖 Books          → 10 entities: Dune, 1984, Sapiens, Zettelkasten
⚛️ Quantum Sims   → 10 entities: qubits, Shor/Grover, Qiskit, VQE
💰 Macroeconomics → 10 entities: GDP, inflation, Keynesian, Phillips curve

Session Lifecycle (Engram Pattern)

Tool	Function
engram_session_start	Creates session record in KG, retrieves previous session's open_tasks + conventions.
engram_session_end	Stores completed_tasks, decisions, open_tasks, conventions_established. Links to project entity.

Wiki Memory (Structured Markdown)

Tool	Function
wiki_read	Read a Markdown page from data/wiki/{path}.md
wiki_write	Write/update a Markdown page
wiki_search	Full-text search across all wiki pages
wiki_list	List all wiki pages

Safety Pipeline (ai-memory-core)

Feature	Function
Prompt Injection Detection	9 regex patterns: instruction override, role switch, system prompt extraction, base64, jailbreak, etc. With risk scoring.
PII Redaction	6 entity types: email, phone, credit card, SSN, IP, API keys.
Provenance	SHA-256 hashing of data dicts for integrity verification.
Limbic Blocklist	Verifier checks KG for inhibit:* entities before allowing tool calls.

Oscillation Scheduler

Real phase tracking (0-2π), not labels:

Mode	Trigger	Behavior
Fast (γ)	workload > 10	Direct routing, skip deep processing
Medium (β)	workload 3-10	Normal cortical cycle
Slow (θ)	workload < 3	Full DMN consolidation, phase coherence gated

Coherence gate: phase_coherence > 0.85 → gate opens → consolidation runs. Based on actual sinusoidal phase calculation.

Quick Start

# Clone
git clone https://github.com/ohmpatel3877/agent-memory-mcp.git
cd agent-memory-mcp

# Install
npm install
npx tsc

# Add to OpenCode config (~/.config/opencode/opencode.jsonc):
# {
#   "mcp": {
#     "agent-memory-mcp": {
#       "type": "local",
#       "command": ["node", "/path/to/agent-memory-mcp/dist/index.js"],
#       "enabled": true
#     }
#   }
# }

Tools (45 Total)

Category	Tools	Count
Base Memory	query_agent_memory, register_resolved_case, create_episode_session, get_temperature, orchestrate_task, get_tool_stats, get_workstream_status, check_contradictions, dedup_cases, query_all_memories	10
Lifecycle	session_bootstrap, session_teardown, observe_operation, memory_health_check	4
Engram Sessions	engram_session_start, engram_session_end	2
Cortical Bridge	cortex_status, cortex_cycle, cortex_pfc_enhance, cortex_acc_strategy, cortex_ofc_persona, cortex_thalamus_route, cortex_bg_optimize	7
Sensory	optical_perceive, touch_observe_tool, get_sensory_summary, audio_spatial_hear, audio_spatial_locate	5
DMN	dream_cycle, get_behavioral_rules, analyze_behavioral_patterns	3
Engine	engine_consolidate, engine_limbic_evaluate, engine_route, engine_columnar_process, engine_oscillation_status, engine_creativity_diverge, engine_creativity_analog	7
Creativity	creativity_session	1
Wiki	wiki_read, wiki_write, wiki_search, wiki_list	4
Domains	seed_domains, get_domain_status	2
Total		45

Evaluation

Metric	Score
Evaluation pass rate	95.5% (21/22)
Logic redundancy	5/5 passed
Speed benchmarks	9/10 passed
Creativity & reasoning	14/16 passed
Code integration	21/22 passed
Module files	33 TypeScript modules
Total lines	~15,000+ across all modules

License

MIT © Ohm Patel