MemAuthority

MemAuthority — Git-Backed Long-Term Memory for AI Agents

中文

MemAuthority is a Git-backed long-term memory system for AI agents, exposed through MCP (Model Context Protocol). It lets a new session, another machine, or another agent recover the project's accumulated context and continue working instead of rediscovering the same decisions and pitfalls.

Rather than attempting to record every single detail, it focuses on distilling:

Lessons and conclusions that future agents should never have to rediscover from scratch.

A clear division of responsibility:

• You act as the gatekeeper: deciding what is truly worth keeping for the long haul;
• The Agent handles execution: understanding, retrieving, summarizing, updating, and pruning memories;
• MemAuthority provides the safety net: keeping long-term memory reliable and available on demand while protecting it from stale writes, duplicate retries, and interrupted updates.

The agent still decides what the content means and whether it should change. MemAuthority makes sure the memory that remains is reliable over time.

---

Who Is This For?

MemAuthority is designed for users who prioritize the quality of long-term memory.

You may have experienced the lack of control with various memory tools:

• Unclear *why* something was remembered;
• Uncertain *when* it will be recalled;
• Unable to verify whether information has become obsolete;
• Left with no clean way to make precise edits or deletions.

Or perhaps you have tried maintaining a memory store, only to watch it grow bloated and messy over time — eventually confusing the agent rather than helping it.

MemAuthority is a good fit when:

Want to invest minimal effort curating memory quality, while delegating all routine organization to the agent.

"Investing effort" does not mean manually editing files all day. It means making high-leverage decisions at key moments:

• Is this information worth keeping long-term?
• When should the memory be reviewed or cleaned up?
• Does any of this involve sensitive data or secrets?
• Does the agent's proposed curation align with your actual intent?

All mechanical heavy lifting — formatting, categorizing, archiving, and targeted retrieval — is handled entirely by the agent.

---

Why Not Just Use MEMORY.md?

If your project's memory is small, rarely changes, or you simply do not want to spend any attention on memory maintenance, sticking with a plain MEMORY.md is the easiest choice.

Once that file stops being just a note and becomes long-term project state that future sessions need to trust, MemAuthority starts to become useful.

It addresses a higher-order need:

Turning long-term memory maintenance into a reliable, controllable, and engineered workflow.

It provides far more than just "letting an agent edit Markdown." It delivers a robust operational architecture:

• Precise On-Demand Loading: Loads memory only when a task actually needs it, preventing irrelevant noise from bloating or polluting the context window;
• Clear Role Separation: Distinctly separates handoff state, standing rules, milestone progress, and pitfall avoidance;
• Concurrency & Version Safety: Enforces strict version checks (CAS — Compare-And-Swap) before writes, preventing stale revisions from silently overwriting fresh content;
• Idempotency & Deduplication: Safe against retries caused by network glitches or aborted runs without creating duplicate memories;
• Convergence & Full History: Keeps the active working memory lean and compact, while relying on Git for complete, auditable revision history;
• Transactions & Crash Recovery: Features explicit journaling and recovery mechanisms in case of interrupted or failed writes.

A useful way to think about it is:

Authority stores the state a future agent should inherit now; Git stores the full history.

In short:

`MEMORY.md` optimizes for simplicity; MemAuthority optimizes for keeping long-term memory reliable as the project grows.

---

Everyday Workflow

You interact with the agent using natural, concise instructions:

1. Retrieve on Demand at Task Start

*The agent decides whether to invoke memory based on actual task conditions, similar to MEMORY.md, or you can instruct the agent to read specific memories:*

"Check this project's MemAuthority — pull in only what you need."

The agent chooses the shortest and most suitable retrieval path, as MemAuthority does not mandate a fixed retrieval method: read directly when the location is known, search when it is not, and use handoff when it needs a quick overall project handoff. If the current conversation already contains enough context, there is no need to call MemAuthority at all.

2. Curate What to Remember

"List the takeaways from this task worth keeping long-term — I'll decide what to save."

The agent distills candidate items, and you make the final call on what to keep, edit, or discard.

3. Quick, Low-Friction Logging

"Record this task."

A common, low-effort command. By default, the agent adopts a conservative strategy — logging it as a low-risk progress entry without altering long-term rules on its own.

4. Post-Task Maintenance

"Review the MemAuthority memory actually used in this task. Update it from what just happened or was verified, and remove anything obsolete."

The agent that just completed the task has the freshest code, tool results, runtime facts, and user decisions. It only needs to maintain the memory it actually read and used, rather than scanning the entire Vault every time.

5. Park Ideas for Later to Free Up Context

"This direction is worth exploring later — drop it in MemAuthority TODO so it doesn't clutter our current context."

Here, a TODO is not a project management issue tracker, but rather:

A staging ground for ideas worth revisiting later, without consuming cognitive bandwidth today.

Once acted upon, the TODO item should be deleted, and any durable conclusions that emerge are promoted to long-term memory.

---

"Record this task" — How to Avoid Memory Bloat?

MemAuthority does not require you to deliberate over "should this go into rules or progress" every time you want to record something.

When you give an open-ended command like *"Record this task"*, the agent's default behavior is:

• Default to `progress`;
• Record only the core deliverables completed in this session;
• Record only meaningful state transitions;
• Record only key context needed for future continuation.

What should be actively filtered out by default:

• Full chat transcripts, conversational filler, and pleasantries;
• Granular, operation-by-operation action logs and trial-and-error details;
• Ephemeral failures with no future reuse value;
• Duplicate facts already documented in the vault;
• Transient, outdated, sensitive, or purely speculative content.

Meanwhile, an agent will not elevate something to a long-term rules entry simply because it "sounds important." Truly solid rules, handoff states, and pitfall lessons should be distilled progressively through real-world work.

System-level guardrails provided by MemAuthority:

• Enforces a standard schema for all written content;
• Restricts mutations based on memory roles (Role-based access);
• Automatically scans and blocks high-confidence secrets and credentials;
• Uses idempotency mechanisms to prevent retries from piling up duplicate entries;
• Uses version validation (CAS) so stale revisions cannot silently overwrite newer revisions;
• Validates candidate vault integrity before committing writes;
• Supports journaled transactions with crash recovery.

The goal is not to "never produce a single low-quality note," but rather:

The agent records conservatively, MemAuthority guarantees underlying state integrity, and ongoing real-world work continuously refines and prunes the memory.

Consistency operates on two distinct layers:

• Semantic Consistency: Maintained by the agent, reconciling new task outcomes with existing knowledge;
• State Consistency: Enforced by MemAuthority, backed by Git Authority, revision CAS, idempotency, and transactional journaling.

Remember: progress is a low-friction entry point for milestone logging, not an immutable, append-only archive.

---

What If I Already Have MEMORY.md or Legacy Notes?

No need to rewrite everything by hand.

For legacy migration, MemAuthority takes a principled approach:

Let the agent perform semantic migration, rather than building custom importers for every legacy format into MemAuthority.

As long as the agent can read and understand your legacy material, it can migrate from any source:

• Existing MEMORY.md files;
• General Markdown or plain text documents;
• JSON exports;
• System prompt files;
• Historical handoffs and chat summaries;
• Conflicting multi-source notes;
• Any other text format an LLM can parse.

Standard Migration Flow:

1. The agent learns MemAuthority's structural specifications and memory standards;
2. The agent reads the legacy notes;
3. It deduplicates, merges, updates, and categorizes information;
4. It strips out obsolete facts, redundant entries, raw logs, ephemeral notes, and unsuitable content;
5. It exports the curated output into the standard MemAuthority vault structure.

You can simply instruct your agent:

"Read MemAuthority's memory specification first, then inspect this legacy memory file. Deduplicate, merge, update, and restructure anything worth keeping long-term. Remove anything outdated, repetitive, raw logs, ephemeral notes, or unfit for long-term storage. Propose a migration draft for my review before writing."

Migration is fundamentally a curation decision, not a mechanical copy-paste.

For initial onboarding or large-scale migration, the recommended v1 workflow is:

init (initialize empty vault)

-> Agent curates vault in detached mode -> validate (verify integrity & schema) -> Human review -> Git commit (commit revision) -> managed serve (launch MCP service)

For the complete guide, see docs/ONBOARDING.md.

---

What Goes into MemAuthority?

Long-term memories in MemAuthority are strictly divided into four roles:

handoff (Handoff State)

The minimal essential context required for an agent to immediately take over the project. Keep it concise, actionable, and continuously updated. It should never become a bloated second README.

rules (Long-Term Rules)

Architectural constraints, standing decisions, and behavioral guidelines future agents must follow. Record only settled decisions, not protracted debates or historical discussions.

progress (Milestone Progress)

Key milestones and state transitions that remain relevant for future work. This is the lowest-friction entry point for logging, but not an append-only transaction log.

pitfalls (Pitfalls & Lessons)

Recurring failure modes, non-obvious traps, and proven workarounds that future agents might encounter. Routine errors and one-off typos do not belong here.

A reliable heuristic:

Will knowing this change a future agent's decisions, save substantial trial-and-error, or prevent repeated mistakes?

If not, it probably does not belong in long-term memory.

---

How to Prevent Unnecessary MemAuthority Memories from Entering Conversation Context?

MemAuthority supports Progressive Recall, but does not require the agent to follow a fixed ritual:

1. If the current conversation already has enough context, do not call MemAuthority at all;
2. If the project is unclear, locate and confirm it first;
3. If the exact URI or section is known, read it directly;
4. If the project is known but the location is not, search within that project;
5. If a quick overall handoff is needed, handoff is usually the best starting point;
6. The agent decides what is relevant and reads only what