Agent Knowledge Bundle - MemForge Design

Core Decision

V1 is private-only. Agent-session memories belong to the uploading user. Repository identity helps grouping and search context, but it is not an authorization boundary.

The design avoids a fallback-heavy system. Robustness comes from stable concept ids, stable claim ids, explicit owner checks, and DB-backed writes. Markdown is rendered from database state for humans and future exports.

End-to-End Flow

Local adapter captures bounded evidence and repo metadata

POST /api/agent-sessions/windows

LLM extracts a durable session outcome or no_output

Server reconciles against private same-user same-repo memories

Service validates owner, visibility, repo, and claim scope

DB writes concept, claim, citation, and memory row

Markdown is rendered from DB state

Search returns private memory rows

Codex / Claude Code
  -> local adapter
  -> /api/agent-sessions/windows
  -> Agent Knowledge Bundle patch + memory lifecycle reconciliation
  -> private concept + claim + citation records
  -> private memory row
  -> memory search

Patch Actions

Action	Meaning	Write Behavior
`create_new_concept`	The evidence starts a new durable topic.	Create concept, claim, citation, and memory row.
`add_new_claim`	The evidence belongs to an existing concept but is a distinct takeaway.	Add claim, citation, and memory row.
`update_existing_claim`	The evidence corrects or refines existing durable knowledge.	Create a new memory row, supersede the old memory, and move the existing claim projection.
`supersede_existing_claim`	The evidence replaces or invalidates existing durable knowledge.	Create a new memory row, supersede the old memory, and move the existing claim projection.
`no_output`	The window has no durable memory value.	Record the processed outcome only.

Storage Model

agent_concepts
  id, source_id, owner_user_id, visibility, repo_identifier,
  concept_type, concept_path, title, markdown_body,
  frontmatter_json, timestamps

agent_claims
  id, concept_id, display_anchor, claim_text, memory_type,
  tags_json, confidence, memory_id, timestamps

agent_claim_citations
  id, claim_id, citation_url, timestamps

The stable projection unit is concept_id#claim_id. Search and lifecycle start from memory rows; when a memory supersedes an older memory, the claim projection moves through agent_claims.memory_id.

Lifecycle-First Reconciliation

session outcome
  -> memory candidate
  -> memory lifecycle
  -> claim projection

The LLM may provide concept and claim ids when the listed context is unambiguous, but the robust path does not depend on the model copying an old claim_id. MemForge resolves the current claim from the matched old memory before moving the projection.

Update Example

First Window

Evidence: scheduler startup failed because overdue schedules were claimed only after UI traffic.
Proposal: create_new_concept
Result:
  concept_id = akb_concept_scheduler
  claim_id   = akb_claim_startup
  memory_id  = mem_123

Later Window

Evidence: scheduler startup is now initialized during app startup.
Proposal: update_existing_claim
Validation: same user, private concept, same repo, claim belongs to concept
Result:
  agent_claims.akb_claim_startup is updated
  memory mem_456 is created
  memory mem_123 is marked superseded
  a citation to the new window is appended

The result is one evolving claim projection pointing at the current memory row, not two active conflicting memories.

Search And Isolation

Search continues to query memory rows. Agent-session memory rows are private, so cloud user A cannot retrieve user B's agent-session memories. Concept markdown is provenance and structure, not the hot-path search store.

Verification Focus

Create private concept, claim, citation, and memory row.
Update an existing private claim by creating a new current memory row and superseding the old one.
Reject another user's private concept.
Keep same-window retries idempotent.
Require cloud HANA adapters to implement the same concept and claim contract methods.