Documentation

Quick Start

Get mem20 running in 60 seconds:

git clone https://github.com/JaysonAIOnline/mem20.git
cd mem20
python -m venv .venv && .venv/bin/pip install -r requirements.txt
MEM20_STORE_PATH=~/.mem20/store .venv/bin/python mcp/mcp_server.py

Then point your MCP host at the server stdio. That's it — 97 tools, 13 domains, zero config beyond the store path.

Architecture Overview

mem20 has four layers that all enforce a single invariant: simulated content never reaches grounded indexes.

Layer	Component	Purpose
Transport	mcp/mcp_server.py	JSON-RPC 2.0 over stdio, tool dispatch
Cognition	cog/cognitive_engine.py	Plan, chain, reason, reflect
Memory	memory_engine/memory.py	Grounded vs simulated store, indexes
Governance	Store-level guards	Contamination firewall, epistemic veto

Memory Partitions

mem20 keeps two logical partitions:

• Grounded memory — facts from real observations, user statements, or events. Indexed via vector embeddings + BM25.
• Simulated memory — hypotheticals, counterfactuals, model output. Never indexed, never reachable by recall.

The Contamination Firewall

Five hard invariants keep the partition real:

1. Vector + BM25 indexes call _assert_grounded() at the lowest write path
2. remember() is grounded-only by default
3. Append-only ledger with validated origin/store tags
4. Promotion requires evidence (prediction resolution or external verifier)
5. Epistemic status stamped directly on the record

Configuration

Variable	Default	Purpose
MEM20_STORE_PATH	~/.mem20/store	Memory engine location
MEM20_LLM_BASE_URL	NVIDIA NIM	LLM chat endpoint
MEM20_LLM_MODEL	(project default)	Model name
NVAPI_KEY	—	LLM bearer token (required)
MEM20_ENV_FILE	—	Optional .env to load keys from

Deployment

For production, mem20 runs as a systemd user service:

sudo ./install.sh --user <user> --dir /opt/mem20

Then verify health:

curl http://localhost:8080/health   # → {"status":"ok", ...}
curl http://localhost:8080/metrics  # → tool counters + contamination_rate

Tool Domains (13)

Prefix	Domain
memory_*	Core memory, epistemic, ingest, pins, namespaces
self_model_*	Agent self-model
cog_*	Cognitive processing
imagination_*	Counterfactual simulation
theory_of_mind_*	Perspective simulation
corrigibility_*	Shutdown / capability tiers
roadmap_*	Roadmap registry
world_model_*	Variables, rules, prediction ledger
affective_*	Values, emotions, goals
procedural_*	Skill library
fs_*	Sandboxed filesystem
blender_*	Blender automation — OPTIONAL
unity_*	Unity automation — OPTIONAL

Governance

Safety is structural, not advisory. The audit command checks both grounded store and BM25 corpus for simulated records:

{ memory_audit_contamination() }

On a clean system this returns contamination_rate: 0.0.

Adding a Tool

1. Pick the domain module for your tool
2. Add self.tools["name"] = mt.Tool(...) to register_<domain>_tools()
3. Add dispatch branch + _name(self, args) handler in the same mixin
4. Keep engine-side invariants intact
5. Run verification/verify_refactor.py

License

MIT. See LICENSE on GitHub.