Skip to content

DR-014 — Knowledge recovery and agent memory

Converted from docs/decisions/DR-014-knowledge-recovery-and-memory.md to MADR (backlog B25). The text is unchanged; its sections are grouped under the MADR headings below, in their original order within each group.

Context

1. Problem (Atul, 20 Oct)

  • Agents forget. Despite reminders and detailed handover prompts, they keep minimal records. API/MM-Cron and PE went backwards twice. MCRM made sample JSONs for categories and product lines, never saved them, and didn't say so.
  • Atul doesn't see agents' real questions and decisions in MMDEP Actions, so he can't step in early.
  • The richest history sits in old chats, many of them outside projects, from the period after the legacy handover.

2. What we have now (20 Oct)

The archive is C:\Projects\_chat-archive\ (local only): 195 chats, 16,642 messages, about 37 MB (roughly 9–10 million tokens).

Folder Chats Account
WPDev 58 C (WPDev, plus the early legacy study)
chats-account-C 19 C
MCRM, MWMC, PE, MMDEP-Assistant 19, 10, 9, 5 A (current projects)
chats-account-A 61 A; includes "API and MM-Cron hourly", "Reconcile NAV Evidence", "PY_API_URL Investigation"
API-MMCron-original 3 B (where API/MM-Cron began)
chats-account-B 11 B; includes "API MM-Cron 1", "API MM-Cron", "Investigate NAV Trigger", "Decide API Compatibility"

Missing: the current API/MM-Cron project's own chats are in none of the exports. Next month's export picks them up.

4. Where Claude differs from the request

  1. ~~Free-tier concern~~: withdrawn, because the key is on the paid tier. Redaction still runs first.
  2. Full chat transcripts don't go into repositories. Session logs hold what the agent showed and did. Complete transcripts stay in the exports and the local archive, so repositories stay readable and safe.
  3. Agents can't write the Claude panel directly. They write issues, which sync to Actions. This is the same outcome through the repository.
  4. MongoDB Atlas isn't needed yet (§3.3).

Options

6. Where Actions and coordination data live: GitHub documents vs a hosted database (Atul, 20 Oct 11:22)

Atul's reason: future agents may not have GitHub or repository access, and should use MMDEP through MCP or other tools we provide.

Need GitHub issues and files Hosted database behind our own MMDEP service (MCP + small API)
Agents without repository access No: each agent needs a GitHub token, and tokens are coarse (repository-wide) Yes: a per-agent token scoped to its project, through the MCP tools we define
Fine-grained permissions (read own project, write only questions) Hard Easy, enforced in the service
Atul answering from the phone Works today (GitHub app) Needs a UI: the Claude panel through a connector, or a small web page
Always on, laptop off Yes Yes, but only while the service is hosted (AWS/Lightsail or similar)
History and audit Built in (issue history) We must design an audit table
Queries and reports (age, blocking, per project) Limited; needs scripts Strong
Cost and effort ~0; about 1 week (#57) Atlas M0 is free (512 MB). Note that MongoDB retired the Atlas Data API, so a hosted service of our own is needed anyway: about 2–3 weeks, plus a small server
Fit with the MMDEP spec Repositories hold content MMDEP holds coordination (spec §2, golden rule 3). MMDEP already has this as a local SQLite hub with an MCP server (mmdep/store.py, mmdep/mcp_server.py)

Decision (Claude, within Atul's "either is fine"): 1. Now (sprints 1–2): GitHub, because it works today with no new service. mmdep actions sync (#57) is built behind a small ActionsStore interface with a GitHub backend. 2. Sprint 3: hosted MMDEP coordination service. Host the existing MMDEP hub (store plus MCP server) as the online MCP gateway (sprint plan v3, sprint 4 item, pulled forward). Add a database backend to ActionsStore: MongoDB Atlas if Atul prefers it, otherwise a managed Postgres or SQLite on the tools server (DR-004). From then on, agents without repository access read and write Actions, questions and decisions through MCP, and GitHub becomes a mirror for people. 3. The database choice is secondary to the service. Choose at sprint 3 design between Atlas (free tier, document model, no server to patch) and SQLite/Postgres on the tools server (already modelled by mmdep/store.py).

Decision

5. Decisions for Atul

  • ~~KNOW-1~~: done. The paid tier is already active.
  • INT-1: approve integration/sprint-1 into main (GitLab harness #56 and the CI change #70; Sonnet synced it, 685 tests passed). This unblocks harness work on the API repository between PROCEEDs.

Consequences

3. The plan

3.1 Knowledge extraction (✔ Gemini paid tier already in place, about $2–5 one-off)

The local job mmdep knowledge extract (Sonnet backlog B12) processes one chat at a time, incrementally: 1. Redact first with deterministic rules: PAN, Aadhaar, phone numbers, email addresses, keys and tokens, passwords and connection strings, IP addresses. Replace them with tags. 2. Gemini Flash-Lite fills a fixed JSON schema per chat: - decisions (who, when, what, why); - requirements and future needs; - facts about legacy systems (hosts, paths, databases, jobs); - data sources; - open questions; - promises and handovers; - scripts or commands used; - artefacts mentioned but not saved (like MCRM's JSONs). 3. Merge per project into docs/knowledge/<project>/: - DECISIONS.md, REQUIREMENTS.md, LEGACY.md, SOURCES.md, OPEN-QUESTIONS.md, LOST-ARTEFACTS.md; - every line cites its chat (date, title, ID), so it can be checked. 4. Order: API/MM-Cron first, then PE, then MCRM (Atul's three worries), then WPDev and its legacy study, then MWMC, then the rest.

Raw chats never go to GitHub. Only redacted, cited extracts do (private repository).

Paid tier confirmed (Atul, 20 Oct): a billed project in AI Studio makes the account's API use paid tier, which is suitable for internal data. Flash-Lite pricing makes the whole archive cost a few dollars, within the ₹3,000 cap.

3.2 Agent memory in the repository (✔ rule §21, applies now)

  • Every PROCEED writes what it shows on screen: the full reply, plus the steps taken and commands run, appended to docs/sessions/YYYY-MM-DD.md in the agent's repository, committed before the reply.
  • Living state files per project:
  • docs/knowledge/CURRENT.md: what's true now, where things are, what's next;
  • DECISIONS.md: every ASSUMED or decided choice, with date and reason;
  • OPEN-QUESTIONS.md.
  • Handover = these files. A new agent reads them first; a handover prompt only points to them.
  • Artefacts are committed when made (JSON, CSV, scripts), never left in chat. "Made but not saved" is a rule breach the Assistant reports.
  • Checks: the collector flags a repository whose docs/sessions/ hasn't changed within 24 hours of other commits, or whose CURRENT.md is older than its last code change (Sonnet backlog B14).

3.3 Questions and decisions reach Atul (✔ ACT-1 in the repository, GitHub, not MongoDB)

  • Agents write directly (rules §21):
  • a business question becomes a question-atul issue (options plus recommendation);
  • a significant decision they took becomes a decision-log issue (what, why, and how to undo it). These show in Actions as "FYI, veto within 48 h", so Atul can step in early.
  • mmdep actions sync (#57, unblocked today):
  • gathers both kinds of issue from every repository after each collector run;
  • writes actions/ACTIONS.md (phone-friendly);
  • reads Atul's replies in the Atul answers issue;
  • relays decisions back.
  • The Claude panel becomes a mirror. MongoDB Atlas isn't needed: GitHub already holds the data, the history, the permissions and the phone app, and adds no new service or secret. Revisit if the volume outgrows issues.
  • The chat extraction (§3.1) seeds Actions with old open questions and undecided items, so years of pending decisions surface once.

3.4 TEA module (◻ design in sprint 2)

  • Script library: from the TEA chats (TEA Chat history…txt, account B and account A NAV chats), extract every investigation command block with its purpose, host, read-only or write classification, and outcome. Store them in tea/scripts/ (MMDEP repo) with an index. Secrets are redacted; only the structure is kept. This is backlog B13.
  • TEA agent spec (sprint 2 design): a read-only evidence collector that runs approved library scripts over SSH through the jobs runner, saves outputs to the inbox, and writes findings to docs/knowledge/<project>/LEGACY.md.

3.5 Documentation Management module (◻ design in sprint 2)

  • Gap report (backlog B15): Gemini compares each project's extracted knowledge (§3.1) with its repository docs, and lists what the repository is missing. Each gap becomes an issue for that project's agent.
  • Weekly freshness check: combined with B14.
  • Later: one index across all repositories, search, and a documentation standard (spec 0.12, #25).

3.6 Epics, fewer PROCEEDs, progress between PROCEEDs (sprint 2; ◻ approve integration/sprint-1 for GitLab)

  • Agents plan at epic level: one PROCEED breaks an epic into issues sized for the harness, each with risk and a routing block.
  • Between Atul's PROCEEDs, the local harness works the small items on GitHub (now) and on GitLab (after integration/sprint-1 is approved: B8). The agent's next PROCEED starts by reviewing what the harness merged, then continues the epic.
  • Target: one PROCEED per agent per day moves an epic forward measurably; the sprint status page (B3) shows it.