A local-first memory layer for AI coding agents. MemoryCore stores your project's
durable knowledge — architecture, decisions, conventions, bug history — as plain
Markdown in a .memory/ directory next to your code, so Claude Code, Codex, Aider,
OpenCode, and any other agent can start each session with real context instead of
re-deriving it.
No cloud. No accounts. No database. No API keys. No LLM calls. Just files in your repo.
Every AI coding session starts from zero. The agent re-reads your codebase to rediscover the same architecture, re-asks why Postgres was chosen over SQLite, and re-introduces the race condition you fixed last week — because the reasoning lived in a closed chat window, not in the repo. Tomorrow's session, or your teammate's agent, knows none of it.
The knowledge that matters — what changed, why, and what it broke or fixed — already exists in your git history at the moment work happens. MemoryCore reads that activity and turns it into a small, reviewed, version-controlled knowledge base that any agent can load and any human can edit.
It is deliberately not a note-taking tool you have to remember to feed. Its
memory learn command inspects your git changes and proposes an entry for you to
confirm — so capturing knowledge is a review step, not a writing chore.
- Stop re-explaining your project. One curated bundle your agent reads at session start.
- Preserve the why. A lightweight, git-native decision log that travels with the code.
- Agent-agnostic. Knowledge captured once exports to Claude Code, Codex, and more — no vendor lock-in.
- Auditable and yours. Plain Markdown, committed to git, reviewed in PRs like any other code.
- Zero trust cost. Everything runs locally and offline. Nothing leaves your machine.
# From a clone of this repo (see Installation for the published-package path)
pnpm install && pnpm build && npm link # exposes the `memory` command
cd /path/to/your/project
memory init
memory learn --manual --type decision \
--title "JWT Authentication" \
--body "Use JWT access tokens with refresh token rotation."
memory query jwt
memory export claudeThat writes a .memory/ knowledge base, captures one decision, finds it again by
keyword, and prints a CLAUDE.md-style context bundle you can hand to your agent.
┌──────────────┐ git status/diff/log ┌──────────────────┐
│ GitService │ ───────────────────────▶ │ AnalysisService │ rule-based, offline
└──────────────┘ (read-only, local) └────────┬─────────┘
│ proposals (you review)
▼
┌──────────────────┐
.memory/*.md ◀────────────────────── │ MemoryStore │ append, newest-first
(Markdown + append + manifest index └──────────────────┘
manifest.json) │
▼
┌──────────────────┐
│ Export adapters │ ─▶ CLAUDE.md / AGENTS.md
└──────────────────┘ style bundles
The store created by memory init:
.memory/
manifest.json # machine-readable index (Markdown is the source of truth)
architecture.md # system structure, components, data flow
decisions.md # decision log (lightweight ADRs)
conventions.md # coding standards and patterns
bugs.md # notable bugs, root causes, fixes, lessons
roadmap.md # planned work, deferred ideas, known debt
README.md # explains the folder to humans who find it
.memory/ is meant to be committed to git. The generated CLAUDE.memory.md /
AGENTS.memory.md bundles are derived artifacts (gitignored by default).
Requires Node.js ≥ 20. MemoryCore shells out to your system git binary for the automatic-learn flow (everything else works without git).
From source (current path — the package is not yet published to npm):
git clone https://github.com/Barosinec/MemoryCore.git
cd MemoryCore
pnpm install
pnpm build
npm link # makes `memory` available on your PATHOr run it without linking, from the repo:
pnpm dev --help # runs the CLI from source via tsxOnce published, global install will be
npm install -g memorycore.
memory initCreated .memory/ with 7 files.
Run `memory learn` to capture your first decision.
memory learn --manual --type decision \
--title "JWT Authentication" \
--body "Use JWT access tokens with refresh token rotation."✓ Saved decision entry
ID: decision-2026-06-14-4mm0
File: decisions.md
memory query jwt[decisions.md]
Score: 100
## JWT Authentication
Use JWT access tokens with refresh token rotation.
memory export claude # prints a CLAUDE.md-style bundle to stdout
memory export codex # prints an AGENTS.md-style bundle to stdoutUse --manual to capture knowledge that isn't visible in a diff (a rationale, a
convention, a decision). Fields come from flags, piped stdin, or interactive prompts.
# Fully flag-driven (great for scripts and agents)
memory learn --manual --type convention \
--title "Prefer named exports" \
--body "Avoid default exports; they hurt refactors and auto-import." \
--tags style,typescript
# Body from stdin
echo "We chose pnpm for workspace hoisting and speed." \
| memory learn --manual --type decision --title "Use pnpm" --stdin
# Interactive (prompts for any missing field, then asks to save)
memory learn --manualEntry types: architecture, decision, convention, bug, roadmap.
Run memory learn with no flags and MemoryCore reads your recent git activity
(status, diff, recent commits, changed files), then proposes structured entries
for you to review. Analysis is deterministic, rule-based, and entirely offline —
there is no LLM, no embeddings, and no network call. It reads git; it never writes to
your source or git state.
A realistic flow — you commit a bug fix, then ask MemoryCore what's worth remembering:
$ git commit -m "fix: stop double-charging on retry (#42)
Disable auth retries on the billing endpoint; refs #42."
$ memory learnProposal 1/1 [bug] confidence: high
Title: Stop double-charging on retry (#42)
Tags: bug
Body:
Commit 81412c9 addressed a bug:
> Disable auth retries on the billing endpoint; refs #42.
Evidence:
- Commit 81412c9 is an explicit fix: "fix: stop double-charging on retry (#42)"
- References #42
- The commit message body describes the change
**Why / Impact:** _<fill in: the root cause, the fix, and the lesson to remember>_
Save [a]ll, [s]kip all, or [r]eview one by one? [a/s/r] a
✓ Saved 1 entry:
bug-2026-06-14-03ny → bugs.md
$ memory query double-charging
[bugs.md]
Score: 100
## Stop double-charging on retry (#42)
...Honest about the heuristics: proposals are inferred from commit-message prefixes
(fix:, feat:), issue references, file shapes, and changed directories. MemoryCore
never invents rationale — it leaves a clearly marked Why / Impact placeholder
for you to fill in. Each proposal carries a low/medium/high confidence based on
how much corroborating evidence it found.
Automation-friendly variants:
memory learn --yes # auto-save only HIGH-confidence proposals; skip the rest
memory learn --dry-run # show proposals, write nothing
memory learn --json # structured { proposalsDetected, saved, skipped, errors }
memory learn --since HEAD~3 # analyze a specific windowIf you're not in a git repository, memory learn prints a clear message and points
you at memory learn --manual. It never crashes.
memory query authentication # ranked, human-readable results
memory query retries --type bug # restrict to one entry type
memory query auth --tag security # restrict to a tag
memory query auth --limit 10 --json # machine-readable outputSearch is lexical (case-insensitive keyword matching with simple field-weighted scoring — title > tags > body). It is transparent and explainable; there is no semantic or vector search.
Both exports read your whole store and render a single, deterministic Markdown bundle.
Output goes to stdout by default; --output <file> writes a file instead.
# Claude Code — a CLAUDE.md-style memory file
memory export claude
memory export claude --output CLAUDE.memory.md
# Codex / other coding agents — an AGENTS.md-style memory file
memory export codex
memory export codex --output AGENTS.memory.md
# Cap the size with a soft token budget (drops lowest-priority entries first,
# never splits an entry, and appends a truncation notice)
memory export claude --max-tokens 2000Entries are grouped by type (Architecture → Decisions → Conventions → Bugs → Roadmap), newest-first within each group, followed by short, agent-specific usage guidance. Identical input always produces byte-identical output, so bundles diff cleanly in git.
See docs/agent-workflows.md for wiring the bundle into Claude Code, Codex, Aider, and OpenCode.
- Local-first and offline. Zero network calls. No accounts, no API keys, no telemetry.
- No LLM, no embeddings. Analysis and search are deterministic and rule-based.
- Read-only on your code.
memory learnonly reads git state and files. It never stages, commits, or edits your source or git history. - Scoped writes. Commands write only inside
.memory/, or to an explicit--outputpath you choose. Nothing else is touched. - Markdown is the source of truth.
manifest.jsonis a rebuildable index; if it disagrees with the Markdown, the Markdown wins.
See SECURITY.md for the full statement and what not to put in .memory/.
MemoryCore is an honest MVP. It deliberately does not include:
- No semantic / vector search. Query is lexical only.
- No LLM-assisted drafting. Auto-learn uses git-metadata heuristics; it summarizes what changed and leaves the why to you.
- Shallow analysis. Heuristics read commit messages, file paths, and diffs — not the abstract syntax tree or dependency graph.
- Conservative
--yes. Unattended saves require high confidence, so a plainfix:with no issue reference or body may be skipped. - No lifecycle tooling yet. No
memory edit/rm/doctor(see Roadmap); hand-edit the Markdown directly meanwhile.
Post-MVP, in rough priority order (nothing here breaks the offline, no-API-key core):
memory doctor— validate the store and rebuildmanifest.json.- Richer offline heuristics (refactor/rename detection, dependency-change awareness).
- More export adapters (Aider, OpenCode, Gemini CLI — the interface already exists).
memory edit <id>/memory rm <id>lifecycle management.- Optional git-hook integration to prompt capture on commit.
- Opt-in LLM-assisted drafting and optional local semantic search — always degrading cleanly to the offline default; never mandatory.
See SPEC.md §11 for the complete roadmap.
- docs/concepts.md — what MemoryCore is and the ideas behind it
- docs/commands.md — complete command + flag reference
- docs/memory-format.md — the on-disk Markdown format
- docs/agent-workflows.md — integrating with each agent
- SPEC.md — the full technical specification
- CONTRIBUTING.md — setup, architecture, and how to extend
Contributions are welcome — especially new analyzers and export adapters. See CONTRIBUTING.md for local setup and architecture.
pnpm install
pnpm typecheck
pnpm lint
pnpm testMIT © Sebastian Barsinec