A 4D memory harness for AI agents.
Navigate a mnemonic palace. Recall only what the goal needs. Stop paying context rot.
Your model does not need a bigger window.
It needs a place to put things, and a way to walk back to them.
Free for everyone. MIT licensed. Clone it, fork it, wire it into Grok / Claude / Codex / your own loop. Third-party notices: THIRD_PARTY.md. Do not commit vendor/ (Apache-2.0 clones and lm-eval task files stay local).
Long sessions rot. Every frontier model degrades as the prompt fills — Chroma's Context Rot study, Anthropic's own engineering notes, BABILong, NoLiMa. Stuffing more history in does not make the agent remember. It makes the agent worse, and more expensive.
Vector databases treat memory as cosine soup. That is an index, not a memory. Humans do not recall by nearest neighbor. They walk a palace.
fourdmem is a harness the agent uses in its work, the same way it uses Lean or Math-Verify: connect, call, get a clean slice, keep going. Two kinds of memory, judged when the note is written against that plan:
- Good — part of the plan. Tied. Stays. Default recall.
- Bad — useless to the creating prompt (cats during a proof). Not deleted. Not tied to the good. Cannot cloud the plan.
The fourth axis (w) is that kind. The first three axes are a palace the agent walks. Navigation of the good graph is recall.
The live prompt stays small. Everything else lives in a git-family content-addressable store and comes back only when the agent walks to it.
prompt (bounded) 4D palace (side channel)
──────────────── ────────────────────────
current goal → go library
latest tool → step n / ascend
recall slice → look / recall
judge good|bad
We do not rewrite conversation history. Dropping old messages to “compress” busts provider caches. fourdmem is a side channel: store, navigate, retrieve. The prefix is sacred.
| Usual memory | fourdmem |
|---|---|
| Dump history into the window | Offload to a lattice; inject ≤512 tokens |
| kNN as the product | kNN is internal; loci are the UX |
| One undifferentiated pile | 3D rooms + valence as the 4th axis |
| Lossy summaries | Lossless CAS (SHA-256, zlib now; pack/delta; zstd in extra [pack]) |
| One pile, or “useful to what I am typing now” | Two kinds, judged at store time vs that plan |
| Pretty dashboards | No lighting. Instant teleports. A retrieval engine. |
The cats test (work loop). Goal at store: prove Hilbert 4D encode/decode is bijective. Hilbert note → good, tied to the plan. “I saw cats on screen” → bad, kept in CAS, not on plan.good. recall is unclouded. Changing the live prompt to a poem about cats does not retie the junk. We do not forget the universe. We do not let it into the plan.
Full write-up: docs/MATH.md. Design: docs/DESIGN.md.
A memory occupies a point on
[ L_4 = \mathbb{Z}^4 \cap \bigl([0,16)\times[0,16)\times[0,8)\times[-8,+8]\bigr) ]
| Axis | Name | Meaning |
|---|---|---|
| (x,y,z) | palace | rooms, floors, landmarks |
| (w) | valence | bad → good, written by judge |
- Hilbert curve (Skilling 2004) folds (L_4) (including (w=+8)) into a 1D pack order. Equal-width 5-bit Skilling on (\iota(x,y,z,w)=(x,y,z,w+8)) padded into ([0,32)^4); 20-bit keys in
uint32.judge gooddoes not fall off the cube. - Product quantization (Jégou 2011) compresses a simhash + n-gram sketch into 8 bytes for placement hints. Original bytes are never destroyed.
- 4D → 3D blanket: the engine renders the affine 3-flat (w = c). Projection ((x',y',z') = \frac{d}{d-w}(x,y,z)). Invertible. No lighting.
- Git-family store:
{type} {size}\0+ SHA-256, zlib loose objects, Hilbert-ordered packfiles, copy/insert delta. zlib now; zstd in optional extra[pack](PR-11). Reconstruction is lossless. - Goal pertinence is a gate, not an axis. Goals change every prompt; putting them on (w) would move the palace. Valence is a property of the object. They compose.
Scale path (real axes, not slogans): 4 = valence (v1) → 5 = epoch → 6 = principle-alignment → 7 = echo/becoming.
Invariants are checked with the same tools labs actually harness to models: Lean 4 (lean/FourDMem at 4.33.1; vendor REPL at 4.34.0-rc2, never mixed) and HuggingFace Math-Verify (harness smoke; Hilbert bijection on (L_4) is the math bar). mini-swe-agent is an optional POSIX-first coding harness, not the only way to land PRs.
Working core is in: goal, store, judge, recall, cas. The agent uses it in work. Kind is judged at store time. Default recall is the plan (good only). Palace/Hilbert PRs still follow the PR plan.
v1 success bar:
- Agent calls fourdmem during a task (same attachment as Math-Verify)
- Two kinds: good tied to the creating plan, bad kept but untied
- Cats stored under a Hilbert goal do not appear in default
recall; CAS still has them - Changing the live prompt does not retie bad onto a new plan
git clone https://github.com/born-lucky/4d-memory.git
cd 4d-memory
uv venv --python 3.12
uv pip install -e ".[dev]"Optional lab harnesses (Lean REPL, Math-Verify source, lm-eval, mini-swe-agent):
pwsh -File scripts/bootstrap-harnesses.ps1fourdmem goal "prove Hilbert 4D encode/decode is bijective"
fourdmem store "Hilbert encode/decode is a bijection on Lattice4."
fourdmem store "I saw cats on screen."
fourdmem recall # good of that plan — no cats
fourdmem recall --kind bad # junk, explicit
fourdmem cas <oid> # lossless, even for bad
fourdmem harness math-verify --gold 1/2 --answer 0.5 # true
fourdmem harness lean --lean-cmd "def f := 2" # {"env": 0}
Full plan (layers, cheats that fail, PR map): docs/TESTING.md.
This is not a website. Labs harness math as local tools you download and call:
| Tool | Where it comes from | What we assert |
|---|---|---|
| HuggingFace Math-Verify | pip install math-verify (PyPI) |
1/2 equals 0.5 → true; 1/2 vs 1/3 → false |
| Lean 4 REPL | clone leanprover-community/repl, lake exe repl |
def f := 2 returns {"env": 0} with no errors |
| Memory work loop | fourdmem itself |
Hilbert note is good; cats are bad and stay out of recall |
pip install -e ".[dev]"
pytest -q
# tests/test_harness.py — Math-Verify true/false + Lean env
# tests/test_work_loop.py — two kinds, CAS still has badLean is skipped only if lake / vendor/math/lean-repl is missing. Math-Verify is a required pip dep; those tests must pass.
Stdio server, same idea as the official Memory MCP and local-first stores (agent-memory-mcp, mcp-memory-service): always-on tools, recall as a tool result, never rewrite the chat prefix. Default recall is good of the plan.
{
"mcpServers": {
"fourdmem": {
"command": "python",
"args": ["-m", "fourdmem.agent.mcp"],
"env": { "FOURDMEM_STORE": ".fourdmem" }
}
}
}Copy-paste config: examples/mcp.json. Details: docs/MCP.md. Or run fourdmem mcp.
fourdmem tools
note store judge go step follow look recall
ascend descend slice mark
principle_assert principle_list
harness_math_verify harness_lean harness_mini_swe
The 3D view exists so the agent has a place. Movement is a dict lookup. Paths are stored as memory. Recurring walks increment echo_count. The store reorganizes itself; landmarks never move.
MIT. Free for everyone — personal, research, and commercial. Pip dependencies and local vendor clones keep their own licenses; see THIRD_PARTY.md. Never commit vendor/ (Math-Verify and lean-repl are Apache-2.0; lm-eval task files are not MIT-by-default).
The repo is public and MIT. Forks, issues, and pull requests are open.
| You want to | Do this |
|---|---|
| Use it | git clone → pip install -e ".[dev]" → fourdmem goal / store / recall |
| Report a bug | Open an issue |
| Help build it | Grab a help wanted issue, or read CONTRIBUTING.md and send a PR |
Binding rules (good/bad at store time, prefix never rewritten, Hilbert must keep (w=+8)) are in docs/DESIGN.md. Math: docs/MATH.md.