Agent memory: a harness-agnostic save/recall/forget contract, shipped as a shareable Skill

[Davidobot]

Summary

LodeDB already ships an MCP "agent memory" server (src/lodedb/local/mcp_server.py) and a one-command installer (lodedb mcp install --client claude-code|codex|cursor|lm-studio|...). But it presents as a database: an extra server with generic tools (lodedb_add, lodedb_search) that an agent has to be wired up to use, plus a config edit the user performs once and then has to teach the agent about.

Modern agent harnesses increasingly ship their own opinionated memory. Coding agents (Claude Code, Codex) and in-house assistants each have an auto-memory system already. A user running one of these does not want to adopt a separate store and learn its tools. They want a plug-and-play skill or link they can hand their existing agent so it improves the memory it already has.

This issue tracks repackaging the existing engine and MCP as exactly that: a thin, harness-agnostic memory contract, delivered primarily as a shareable Skill, local-first. It adds no storage logic; this is a packaging and framing layer over what already exists.

What we're building

• A small, harness-agnostic memory contract: save, recall, forget (and stats), specified once, independent of any single harness. This is the thin standardized interface; LodeDB is the layer behind it, so the same memory drops into different harnesses.
• Two memory modes, configurable per agent:
  • Augment: index the agent's existing memory artifacts (CLAUDE.md/AGENTS.md, a memory directory, transcripts) so recall over the agent's own notes becomes semantic. The agent's native memory stays the source of truth.
  • Store: a separate durable long-term memory the agent saves to and recalls from, for harnesses whose native memory is closed.
• A Skill (SKILL.md plus a thin wrapper) as the primary artifact the agent loads. It encodes the policy (what is worth saving, recall before answering, update vs append) and implements the contract over the existing CLI/MCP. Shareable as a link or path rather than a config edit.
• Reference adapters over the single contract: Claude Code (skill plus MCP), Codex (AGENTS.md plus config.toml), and a generic MCP/HTTP shape a custom in-house harness can call without a bespoke integration.
• Local-first. The link or installer stands up an on-disk LodeDB and data stays on the machine, consistent with the existing stdio, no-auth MCP server.

What exists today (reuse, do not rebuild)

• src/lodedb/local/mcp_server.py: stdio MCP server, no auth, on-disk, returns each hit's stored text inline, hybrid (BM25 + vector) ranking by default, redaction flags (--exclude-text, --no-store-text). Already described in its own docstring as "local agent memory."
• src/lodedb/local/mcp_install.py: writes the correct config entry per client (claude-code, claude-desktop, cursor, lm-studio, codex), resolves the launch command and absolute paths, idempotent and non-destructive to other servers.
• The engine itself (durable single-add via WAL, hybrid search, metadata filters) is the memory store. This work adds no storage logic on top of it.

Staged approach

The existing MCP server keeps working unchanged at every step.

1. Define the contract. Write save/recall/forget/stats as a one-page spec, independent of harness. Map it onto the current MCP tools (memory-semantic names or aliases) and add a server-provided usage instruction so any MCP host uses it correctly with no bespoke wiring.
2. Ship the Skill. A SKILL.md plus thin wrapper implementing the contract over the CLI/MCP, encoding memory hygiene (salience, recall-before-answer, update vs append). Validate end to end on one harness before generalizing.
3. Augment mode. Add an "index existing memory" command that points LodeDB at the agent's own artifacts and keeps a semantic index synced as they change. Make store vs augment a configuration switch rather than two code paths.
4. Adapters and one-line installer. A generic MCP/HTTP rendering for a custom harness, plus a uvx-style installer that detects the agent, wires the config, and drops the skill, so the shareable link becomes a single command.

Open questions

• Augment for closed harnesses. Claude Code and Codex native memory is not a public writable backend, so augment means "index their memory files and transcripts," not "become their backend." Confirm which artifacts are worth indexing per harness.
• Skill portability. SKILL.md is an Anthropic convention that other harnesses are adopting; for a fully custom harness the contract is the portable unit and the skill is one rendering of it.
• Memory hygiene policy. Dedup, update vs append, and decay/forgetting. The project's own memory layout (one fact per file plus an index) is a useful reference shape.
• Packaging name. A dedicated lodedb-memory entry point versus a subcommand of lodedb.

Out of scope

• Hosted or multi-device memory. Local-first only for now. The contract should not preclude an optional hosted sync later, but no server, auth, or sync is built here.
• Changes to the storage engine or on-disk format, tracked separately in Consolidate the engine into a native lodedb-core crate with thin language bindings #27.

[saifu8nnn]

Hey @Davidobot,

I’d love to take a swing at the first two stages of this (Defining the contract & Shipping the Skill).

Since the core MCP server and storage engine are already handling the heavy lifting, my thought is to keep this abstraction as thin as possible. Here is my rough plan for Stage 1 & 2:

1. Defining the Contract (Python / MCP side)
   I can map the existing MCP tools to semantic, memory-focused aliases so they act as a clean CRUD interface for the agent:

lodedb_add -> mapped to save (with logic to handle append vs. update based on the agent's intent).

lodedb_search -> mapped to recall (leveraging the existing hybrid search).

lodedb_remove -> mapped to forget.

lodedb_stats -> mapped to stats (for agent context awareness).

2. Shipping the Skill (SKILL.md)
   I'll draft the initial SKILL.md wrapper. This will essentially be the policy engine instructing the LLM on memory hygiene, such as:

Recall before answering: Always trigger a recall query when starting a new session or encountering an unknown entity.

Salience: What constitutes a fact worth a save (e.g., user preferences, architectural decisions) vs. transient chat.

If this direction aligns with what you have in mind for the first iteration, I can start putting together a PR for the contract mapping and the draft of the SKILL.md. Let me know!

[Davidobot]

@saifu8nnn sure thing, go for it!

[saifu8nnn]

@Davidobot PR is up - #42

[ajdelaguila]

Full disclosure: I maintain Data Olympus, a governed project-knowledge MCP server for coding agents: https://github.com/knaisoma/data-olympus

The harness-agnostic save / recall / forget contract is a strong framing. One extension worth considering is an explicit distinction between “remember this happened” and “use this to govern future behavior.”

In practice, coding agents need both:

• general memory: observations, preferences, task state, past fixes;
• governed knowledge: accepted standards, decisions, runbooks, constraints, and supersession history.

Those have different lifecycle rules. A captured observation can be useful but provisional. A governing rule should usually have status, provenance, validity, and a review/promotion path before retrieval gives it authority over future work.

Data Olympus focuses on that second layer: git-native markdown, MCP retrieval, proposed writes, accepted/in-force filtering, validity windows, and supersession chains. It could sit beside a storage engine like LodeDB, or serve as a reference for the “authority and lifecycle” metadata in the contract.

For this issue, the key API addition may be less a new verb and more a metadata envelope on saved items: status, valid_until, last_verified_at, supersedes / superseded_by, and scope.

[saifu8nnn]

Hey @Davidobot Is there anything you think must be changed on what i pushed then let me know about it.
Thanks