MemForge

Typed, git-native, dynamic memory for coding agents. A markdown folder + a small spec + reference tooling. Works across Claude Code, Cursor, Aider, Codex, and GitHub Copilot Chat through thin adapters. As of v0.5, supports multi-operator teams with cryptographic attribution; as of v0.5.2, the reference CLI ships under a single memforge dispatcher with cross-platform support (macOS, Linux, native Windows); as of v0.6, query-triggered recall surfaces the memories matching a prompt on demand instead of bulk-loading the whole index.

Docs: PyPI | CHANGELOG | spec | examples

Status: pre-1.0; external PRs paused. Issues and Discussions are open. External pull requests are paused until the Contributor License Agreement infrastructure lands. See CONTRIBUTING.md. Security reports go through the private channel in SECURITY.md.

Quickstart (v0.5+, ~3 minutes)

pip install ildan-memforge
memforge --version                  # memforge 0.8.1
memforge init-operator --name "Your Name" --gen-key
cd /path/to/memory-root
memforge init-store                 # creates the signed operator-registry first
memforge recovery-init              # anchors the recovery-secret SHA256 in that registry
memforge recovery-backup-confirm --i-have-backed-up-the-secret
memforge messaging-doctor           # verify v0.5 posture: ALL CHECKS PASSED

Full quickstart at docs/quickstart.md (includes a section on commit hygiene + the signed memforge: commit-prefix grammar that audit / resolve / revoke parse). Multi-operator team bootstrap at docs/team-bootstrap.md (includes "Pick your transport: git-only or WebSocket?" decision-framing for teams sizing the v0.5 messaging adapter).

Cite this work

If you use MemForge in research or publications, please cite:

Hiltz, Mike. MemForge: Portable, agent-neutral persistent memory format for AI coding agents (v0.10.0). Zenodo, 2026. DOI: 10.5281/zenodo.20113963

The DOI above is the version-agnostic concept DOI; it always resolves to the latest archived release.

The gap MemForge fills

Coding agents have static instruction surfaces (AGENTS.md, .cursorrules, CONVENTIONS.md, .github/copilot-instructions.md, Claude Code's auto-memory) for things you want the agent to read at the start of every session. They handle the "always-true" half well.

What they don't handle: the changing half. The fact that you decided to use bun not npm last Tuesday. The reason you rejected the obvious database schema. The post-incident rule about not mocking the staging API. The seven things you've told four different agents the same way and are tired of repeating.

That state belongs in memory: typed entries that the agent can read, write, audit, and version-control alongside the code. MemForge is the format for that memory and a small set of tools that keep it healthy.

What you get

• A folder of markdown files with YAML frontmatter. Hand-editable, diffable, code-reviewable.
• Four memory types: user (facts about the developer), feedback (rules they have given), project (state about ongoing work), reference (pointers to external systems).
• A MEMORY.md index any agent loads at session start.
• Rollup subfolders for topic clusters of five or more memories, so the index stays scannable.
• Audit + integrity tooling that runs in CI: schema checks, link integrity, DLP scan, tamper-evident audit log.
• Adapters for Claude Code, Cursor, Aider, OpenAI Codex, and GitHub Copilot Chat (VS Code).

60-second install

pip install ildan-memforge

The PyPI distribution is published under ildan-memforge because the shorter memforge name is held by an unrelated project. The Python import path is still memforge, and the 20 CLI commands install with the same names (memory-audit, memory-watch, memory-dlp-scan, memforge-resolve, etc.). You can also install straight from source:

pip install git+https://github.com/ildan-ai/memforge.git

macOS / Homebrew Python (PEP 668)

On macOS with Homebrew Python, pip install against the system interpreter is blocked by PEP 668 (error: externally-managed-environment). Use one of:

# Option A: pipx (recommended; isolates the install)
brew install pipx
pipx install ildan-memforge

# Option B: dedicated venv
python3 -m venv ~/.local/share/memforge/.venv
~/.local/share/memforge/.venv/bin/pip install ildan-memforge
# then symlink the binaries into a directory on $PATH

# Option C: --user --break-system-packages (last resort; pollutes brew Python)
python3 -m pip install --user --break-system-packages ildan-memforge

The same caveat applies on most Linux distributions that mark their system Python EXTERNALLY-MANAGED (Debian 12+, Ubuntu 23.04+, Fedora 38+, etc.).

Pick a folder for your memory. The IDE-neutral default the tooling resolves to:

~/.memforge/global-memory/   # cross-project rules
~/.memforge/memory/          # per-cwd state

Resolution order is: the MEMFORGE_PATHS environment override, then a grandfathered Claude Code layout (~/.claude/global-memory/ plus ~/.claude/projects/<USER>-claude-projects/memory/) if it already exists, then the ~/.memforge default above. So an existing Claude Code store keeps working untouched, and a fresh install lands under ~/.memforge.

Other layouts work too; the tooling takes a --path argument everywhere.

A memory file, end-to-end

---
name: Use bun, not npm
description: Bun is the package manager for this monorepo
type: feedback
uid: mem-2026-04-12-use-bun-not-npm
tier: index
tags: [topic:tooling, topic:javascript]
owner: web-platform
status: active
created: 2026-04-12
---

When installing or running scripts in this repo, use `bun` and `bunx`. Lockfile is `bun.lockb`.

**Why:** the workspace setup at `apps/web/package.json` relies on bun's workspace resolver; npm pulls a slightly different dependency tree and the build fails downstream.

**How to apply:** any time you reach for `npm install`, `npx`, or a `package-lock.json`, stop and use bun instead. If a script in the README still says `npm run`, treat that as a docs bug, not a directive.

That file is the unit. Every tool, every adapter, every check operates on files of exactly this shape.

When MemForge is the right tool

• You move between coding agents and want them to share the same notes.
• You want memory entries reviewable in pull requests, like code.
• You want the operator to see what the agent has written about them and edit it freely.
• You want CI gates on memory hygiene (broken links, secret leakage, schema drift).

When it is not

• Not a vector database. No embeddings, no similarity search at runtime. Use mem0 or letta if that is the shape you need.
• Not a secrets store. The DLP scanner refuses files that look like they leak credentials, but the format is human-readable plain text. Keep secrets in a vault.
• Not a runtime memory layer. MemForge is the file format and the discipline, not a service. Adapters load files into agent context at session start; nothing runs continuously.
• Not a replacement for AGENTS.md. AGENTS.md is the README for agents (static, repo-level, project setup). MemForge is the working notebook (dynamic, evolving, often per-developer). They coexist.

How it compares

The honest summary: if your agent is a long-running service that needs to remember a thousand things from yesterday's chat, you want a vector store. If your agent is a coding session that needs to remember the rules and decisions a human cares about across sessions, you want MemForge.

Architecture

flowchart LR
    Dev[Developer] -->|edits| Folder[Memory folder<br/>markdown + YAML]
    Folder -->|read at session start| AdapterCC[Claude Code adapter]
    Folder -->|read at session start| AdapterCursor[Cursor adapter]
    Folder -->|read at session start| AdapterAider[Aider adapter]
    Folder -->|read at session start| AdapterCodex[Codex adapter]
    Folder -->|read at session start| AdapterCopilot[Copilot Chat adapter]
    AdapterCC --> Agent1[Claude Code]
    AdapterCursor --> Agent2[Cursor]
    AdapterAider --> Agent3[Aider]
    AdapterCodex --> Agent4[OpenAI Codex]
    AdapterCopilot --> Agent5[GitHub Copilot Chat]
    Folder -->|CI gate| Tools[memory-audit<br/>memory-dlp-scan<br/>memory-link-rewriter<br/>memory-audit-log]
    Tools -->|fail PR on violation| GH[GitHub Actions]
    Folder -->|append-only| ChainLog[(.memforge-audit-log.jsonl<br/>tamper-evident chain)]

Adapters are thin: they translate "load this folder at session start" into the agent's native rules surface. Adding an agent means writing a new adapter, not changing the format.

Key tools

Run --help on any of them.

v0.5+ operator + identity surface (under the memforge dispatcher)

v0.3 / v0.4 memory-format surface (per-tool console scripts)

Competing-claim consolidation (standalone console scripts)

These ship as standalone console scripts today, not as memforge dispatcher subcommands (dispatcher integration is tracked in spec/known-limitations.md §"Reference CLI status").

memforge <subcommand> --help (dispatcher subcommands), <tool> --help (standalone console scripts), and tools/README.md have the long-form references.

Spec

Format invariants are in spec/SPEC.md. Topic taxonomy is in spec/taxonomy.yaml. The current package version is in pyproject.toml; the on-disk format version is in spec/VERSION. They track separately on purpose: a tooling release does not always shift the format, and a format bump is a deliberate event.

Status

The reference implementation is running in production. External adoption is welcome once the CLA flow is live.

License

Apache-2.0. See LICENSE.

The "MemForge" name and logo are subject to pending trademark filings; the Apache-2.0 grant does not cover the marks. A trademark policy will land alongside the v0.3.x CLA release.

Contributing

External pull requests are paused. Issues and Discussions are open. See CONTRIBUTING.md for the current model and the post-CLA contributor flow.