v0.4.3 — agentbrain rules: install memory discipline into any client

The discipline-installer release

Registering an MCP server makes the memory tools available — but most clients
only call them if a rule file tells them to. That was the last manual gap:
you had to hand-write "query the vault at task start" into every client. Now
one command does it.

agentbrain rules — install the memory discipline anywhere

Run it in any project root:

agentbrain rules                              # print the discipline block (generic)
agentbrain rules --agent claude --write       # CLAUDE.md
agentbrain rules --agent codex --write        # AGENTS.md
agentbrain rules --agent trae --write         # .trae/rules/project_rules.md
agentbrain rules --agent cursor --write       # .cursor/rules/agentbrain.mdc (alwaysApply)

The block installs the full three-phase workflow:

• Task start — memory_query (top_k=5) with the task topic; read hits first
• Mid-task — re-query on a new subtask, an error, or a topic switch the
  initial query didn't cover (plain continuation re-queries nothing — token
  discipline)
• Wrap-up — memory_ingest each distinct reusable lesson, with user confirmation
• Secrets — never enter the vault; ${ENV:VAR_NAME} placeholders instead

Safety properties, locked by tests:

• Existing rule files are never overwritten — if you already have
  CLAUDE.md or .trae/rules/project_rules.md with your own content, the
  block is appended. Your rules stay byte-identical.
• Idempotent — a marker detects prior installation; re-runs are no-ops.

Also in this release

• ONBOARDING.md now suggests the owner run rules --write after wiring up a
  new agent's MCP, closing the loop: onboarding → tools available → discipline
  installed.

Verification

• 95 tests (8 new: block rendering per agent, file creation, append-not-overwrite
  on pre-existing user rules, idempotency, unknown-agent error path)
• CLI smoke test: agentbrain rules prints the block; --write paths verified
  on tmp fixtures
• Wheel + sdist built, twine check PASSED, published on PyPI:
  https://pypi.org/project/mnemosyne-lite/0.4.3/

pip install --upgrade mnemosyne-lite

v0.4.2 — Self-service onboarding + hardening

The self-service onboarding release

Three improvements shipped together — no new subsystems, just sharper edges.

ONBOARDING.md — new agents wire themselves up

Every vault now ships with a one-shot guide next to AGENTS.md. Onboarding a
new agent (Claude Code, Codex, Cursor, DSH, anything) is now a single sentence:

"Read AGENTS.md and follow it."

AGENTS.md routes first-timers to ONBOARDING.md, where they check which
access mode they are in:

• Have memory_* tools → MCP already wired, go work.
• Shell access → register the MCP server in their own client (name,
  command, env spelled out), restart, verify with memory_profile.
• File access only → read Index.md, grep Learnings/ — and explicitly
  told NOT to hand-write lesson files (ids/index consistency), secrets stay out.

Existing vaults get it via agentbrain init (idempotent) or by copying the
template file.

Secret redaction closes its last gaps

memory_ingest previously scanned only the lesson body and summary. A
credential smuggled into case_id (→ lands in the filename and frontmatter)
or tags (→ frontmatter) could slip past. All four inputs now go through the
same scanner. Placeholders (${ENV:VAR}, sk-xxx) remain exempt.

Hand-edited frontmatter can no longer poison the vault

A lesson file with confidence: high or use_count: many (typed by hand in
Obsidian) used to crash every vault read — queries, lint, doctor, everything.
Each numeric field now falls back to its default per-file; one bad file never
breaks the rest.

Verification

• 87 tests (3 new: credentials in case_id/tags refused; bad-numeric frontmatter
  tolerated with defaults; ONBOARDING.md present in scaffolding)
• Live vault regression: existing lessons unaffected, doctor healthy
• Wheel + sdist built, twine check PASSED, published on PyPI:
  https://pypi.org/project/mnemosyne-lite/0.4.2/

pip install --upgrade mnemosyne-lite

v0.4.1 — Enforced secret redaction

The secret-redaction release

"Secrets never enter the vault" was a rule; now it's a mechanism.

Now on PyPI

pip install mnemosyne-lite

The distribution name is mnemosyne-lite — agentbrain was rejected by PyPI as too
similar to an existing project. The CLI command and the Python import name remain
agentbrain, and the GitHub repo keeps its name. Python >= 3.10.

Enforced on write

memory_ingest now scans lesson content and summaries for credential-shaped content before writing:

• OpenAI / Anthropic keys (sk-…, sk-ant-…)
• GitHub tokens (ghp_/gho_/ghu_), AWS keys (AKIA…, 40-char secrets)
• Slack (xox…), Google (AIza…), PyPI tokens
• Authorization: Bearer … headers, private-key blocks
• Generic password= / api_key= / secret= / token= assignments

On a hit the write is refused with a clear message telling the agent to substitute an ${ENV:VAR_NAME} reference — the value stays in env/keyring, the lesson stores only where to find it.

Designed to not fight you

• ${ENV:VAR} references, sk-xxx stand-ins, YOUR_KEY / <placeholder> teaching examples all ingest normally — zero false positives on real-world prose (verified against a live vault).
• lint now also reports SECRET findings for pre-existing lessons — read-only as always; lint never modifies files.
• The boundary stays "block the machine, not the owner": agents get refused, hand-written files are never touched.

Verification

• 84 tests (10 new: pattern detection, placeholder exemption, ordinary-prose non-matches, ingest refusal + non-write, lint reporting + file untouched)
• Live vault: 15 real lessons → zero false positives; fake credentials refused; placeholder lesson accepted
• Published on PyPI: https://pypi.org/project/mnemosyne-lite/0.4.1/ (wheel + sdist, twine check PASSED)

v0.4.0 — Maintenance mode: git snapshots + doctor + fool-proof install

The maturity release

agentbrain is now feature-complete for its core promise — a local, token-efficient, agent-shared long-term memory that you own as plain Markdown — and enters maintenance mode (bug fixes and compatibility only).

Git snapshots — point-in-time recovery for your memory

Every vault is now its own git repository (created automatically by agentbrain init, with repo-local identity — your global git config is never touched). Every content write is an auto-commit:

• memory_ingest → ingest: case-x-lesson-01
• agentbrain apply → apply: <proposal>
• lint / distill proposals, profile suggestions, index rebuilds — all committed

Any bad edit — yours, an agent's, or Obsidian's — rolls back with plain git. Query-driven use_count bumps deliberately ride along with the next content commit to keep history readable. Everything degrades gracefully: no git installed → snapshots silently disabled, zero impact.

agentbrain doctor — one command, whole picture

agentbrain 0.4.0 · Python 3.10.11
vault: C:\Users\you\agentbrain
lessons: 15 active
index: fresh
lock: acquire/release ok
snapshot: enabled · last: Fri Aug 21 16:14:17 2026 — index: rebuild
log: 18 entries

Everything looks healthy.

Plus a copy-paste MCP client config with your vault path already filled in (JSON-escaped on Windows).

Fool-proof install

README now opens with a 3-step quickstart: pip install agentbrain → agentbrain init → paste one JSON block into any MCP client. That's the whole setup.

Verification

• 74 tests (9 new: snapshot lifecycle, no-git / no-repo graceful paths, doctor healthy & stale-index detection, apply/init/suggest auto-commits)
• Wheel + sdist built, twine check PASSED (PyPI-ready)
• Live MCP stdio smoke: 6 tools + 3 resources, ingest auto-commits to the vault git history

PyPI publication is the remaining step — issue tracker open for bug reports.

v0.3.2 — OS-level vault lock + edge-case fixes

Locking rewrite (headline)

The vault lock now uses OS-level byte-range locks (msvcrt.locking on Windows, fcntl.flock on POSIX) instead of the previous create-file + 60-second-stale-reclaim scheme. Two real problems disappear:

1. Crash availability: if an agent process crashed while holding the lock, every writer to that vault failed with VaultLockTimeout for up to 60 seconds. OS locks are released by the kernel at process death — the next writer acquires immediately. Covered by a dedicated test that kills a lock-holding subprocess and asserts instant re-acquisition.
2. Stale-reclaim race: two waiters could both judge the lock stale, both unlink it, and both acquire — silently breaking mutual exclusion. There is no stale concept to race over anymore.

The lock file (.vault.lock) now persists on disk; removing it while a holder might exist would break exclusion, so it is never unlinked. It is never indexed or treated as a lesson.

Other fixes

• agentbrain lint --scope tag:x no longer reports false DANGLING findings for supersede targets that exist outside the requested tag scope.
• case_ids containing glob metacharacters ([, ?, *) no longer cause lesson-id collisions that could silently overwrite an existing lesson (exact-prefix regex scan replaces the raw glob).
• Suggestion files (memory_suggest) now use real YAML frontmatter — titles containing colons or newlines used to corrupt the header — and are written atomically.
• atomic_write temp-file names include the thread id, so same-process concurrent writers can never share a temp file.

Verification

• 65 tests (6 new/updated: killed-holder release, leftover-lock-file non-blocking, timeout-while-held, YAML-injection roundtrip, tag-scope DANGLING, glob-metachar ids)
• Cross-process smoke: 4 independent processes ingesting into the same case concurrently — 20/20 lessons landed, no loss, no lock timeouts

v0.3.1 — Data-integrity fixes

Bug fixes (data integrity)

Same-case concurrent ingest no longer loses lessons

The most serious issue found this round: when two agents ingested lessons for the same case at the same moment (e.g. TRAE and Claude Code working on the same topic), both drew the identical lesson id (case-x-lesson-01) and the second write silently overwrote the first. Lesson-id allocation now happens inside the vault lock, so parallel ingests always get distinct ids.

confidence: 0.0 round-trips correctly

A classic falsy trap: lessons saved with confidence exactly 0.0 were loaded back as 0.8, hiding low-confidence lessons from lint's LOWCONF check.

lint / distill proposal races

Proposal files were written with plain write_text on second-resolution filenames. Concurrent runs in the same second could clobber or tear each other's files. Proposals are now written atomically under the vault lock with collision-free names.

Smaller fixes

• Merge proposals now keep the more-used lesson as the keeper (merge direction follows use_count).
• Duplicate detection pre-tokenizes each lesson once instead of re-tokenizing every pair (O(n²) comparisons, no per-pair tokenization).
• apply audit-log entries no longer embed | inside the logged object (broke structured log parsing).

Verification

• 59 tests (5 new regression tests: concurrent same-case ingest, confidence-0 roundtrip, same-second distinct proposals, merge direction, query bump)
• Smoke-tested against a live vault (lint clean, query hits)

Full changelog: see Changelog section in README.md.

v0.3.0 — Concurrency safety & robustness

Highlights

Concurrency safety (multi-agent ready)

Several agents (TRAE, Claude Code, Codex, ...) writing the same vault at the same time no longer corrupt state:

• Vault write lock — cross-process and cross-thread mutual exclusion via a transient .vault.lock (atomic O_CREAT|O_EXCL creation, re-entrant within a thread, stale locks auto-reclaimed after 60 s).
• Atomic writes — every file write goes through temp-file + os.replace, so concurrent readers never see torn Markdown.
• agentbrain apply is a transaction — validation and supersede writes happen under one lock; a vault changed mid-apply is refused with zero side effects.

Performance & robustness

• memory_query no longer rebuilds the index once per hit — one rebuild per query regardless of top_k.
• Stray non-lesson .md files dropped into Learnings/ (e.g. a README) are ignored instead of polluting the index.
• memory_ingest confidence is clamped to [0, 1]; unknown mode values fall back to index.
• Same-second profile suggestions no longer overwrite each other.

Verification

• 54 unit/integration tests (10 new: lock re-entrancy, thread serialization, timeout & stale-reclaim, concurrent ingest, single-rebuild queries, stray-file skipping, input clamping)
• Cross-process smoke: 4 parallel CLI processes ingesting into one vault — all succeeded, zero lost lessons/log entries, lock cleaned up
• MCP stdio smoke against a live vault: 6 tools + 3 resources registered and callable

Full changelog: see Changelog section in README.md.

v0.2.0 - first public release

Local-first long-term memory for AI agents: a plain Markdown vault + a thin MCP server.

Highlights

• 6 MCP tools: memory_query / memory_ingest / memory_lint / memory_distill / memory_profile / memory_suggest
• 3 MCP resources: agentbrain://rules, agentbrain://index, agentbrain://profile
• CLI: init / query / ingest / lint / distill / profile / suggest / apply / index / path / serve
• Vault: plain Markdown, Obsidian-friendly, Git-friendly; Index.md as cheap retrieval layer 1
• Retrieval: CJK-aware BM25 (Chinese works out of the box), boosted by verified/use_count/recency
• Self-maintenance: lint writes human-approved merge proposals; apply executes them transactionally; distill promotes recurring patterns
• Profile layer: agents read owner preferences and propose changes via suggestions - never edit directly
• 44 passing tests; compatible with both mcp 1.x and 2.x SDKs

Install

pip install git+https://github.com/2672243194/agentbrain.git@v0.2.0

Requires Python >= 3.10.