KnowledgeMCP Knowledge Graph & Shared Memory

MCP Knowledge Graph & Shared Memory

MCP Knowledge Graph & Shared Memory

Version: 2.0 Last Updated: 2026-03-15 Status: Active operational policy

This document defines how agents must use the project-local AIM Knowledge Graph for shared Jorvis memory.

Purpose

The project-local KG is the durable shared-memory layer for:

  • approved sequencing decisions
  • GO / NO-GO outcomes
  • verified runtime or deploy truth
  • active blockers
  • role-routing facts that matter across sessions

It is not the source of truth for every fast-moving repo or PR detail.

Canonical Sources and Precedence

Current-state precedence:

  1. live git and live PR state
  2. project-local AIM KG (location="project", context="jorvis")
  3. docs/handoff/HANDOFF_TO_NEXT_AGENT.md
  4. docs/agent_ops/TASK_BOARD.md
  5. docs/agent_ops/GO_NO_GO.md

Use the KG to preserve durable shared context. Use live git / GitHub state for exact review heads, CI status, and mergeability.

Canonical Store

  • Location: project
  • Context: jorvis
  • Backing file: .aim/memory-jorvis.jsonl

Do not write Jorvis runtime state to global memory without explicit Gatekeeper GO.

Session Bootstrap

At session start:

  1. call aim_memory_list_stores()
  2. confirm project-local detection
  3. read only the relevant compact *_Current entities with aim_memory_get(...)
  4. stop and escalate if project mode is not active

Recommended current entities:

  • Knowledge_Graph_Runtime_Policy
  • Jorvis_Project_Current
  • Jorvis_Runtime_Current
  • Jorvis_Prod_Parity_Current
  • Jorvis_Roles_Current

Read additional entities only when they are directly relevant to the task.

Reread Cadence

Reread the relevant KG entities:

  1. after a merge, rebase, base-SHA refresh, or worktree switch
  2. before gate/test/deploy/final recommendations when live state may have changed
  3. after a long-running executor/tester lane
  4. before writing a new coordination packet if repo or PR state changed while drafting

What Belongs in Memory

Write only durable, important facts such as:

  • GO / NO-GO outcomes
  • ADRs and architecture decisions
  • verified runtime/deploy truth
  • active blockers
  • approved sequencing changes
  • role-routing changes that matter beyond the current turn

What Does Not Belong in Memory

Do not write all of the following by default:

  • every CI rerun
  • exact current PR head SHA
  • mergeable / CLEAN / green / pending status
  • branch-local scratch notes
  • repeated review loops already captured in OUTBOX
  • transient observations that will stale after the next merge

Exception:

  • a transient fact may be stored when it is itself the active blocker being tracked

Durable Formatting Rules

Jorvis_*_Current entities must be written to survive routine docs-only merges and review-head churn.

Good current-memory facts:

  • "Prod parity is blocked by the active deploy-script idempotency bug."
  • "PR-C must not start until prod parity is restored and SSOT is refreshed."
  • "Tester owns post-deploy smoke by default."

Bad current-memory facts:

  • "origin/main is exact SHA X" as a long-lived current-memory fact
  • "PR #507 is green on head SHA Y" unless that exact live PR state is the blocker
  • "mergeable=CLEAN" as persistent memory

Exact heads, CI state, and mergeability should normally be re-read from live git / GitHub state.

Compaction and Cleanup Rules

  • Keep *_Current entities compact.
  • Move detailed lineage and command output to OUTBOX/docs.
  • Historical/task/dated entities should be short outcome summaries, not long per-commit logs.
  • If a fact becomes stale, duplicated, or irrelevant, update or remove it instead of appending more drift.
  • Prefer aim_memory_remove_facts, aim_memory_forget, or compact replacements over uncontrolled growth.

Worktree Rules

  • Worktrees must still resolve the canonical project-local memory files.
  • The checked-out repo-root MEMORY.md remains the bootstrap note inside worktrees.
  • Do not trust worktree memory if project-local detection is broken.

Commit Policy

.aim/*.jsonl files are runtime state. Do not stage or commit them.

Operational Pattern

Use this pattern:

  1. read live git / PR state
  2. read relevant compact KG current entities
  3. reconcile conflicts explicitly
  4. act or draft based on live truth
  5. update KG only if durable truth changed
  6. compact stale memory during closeout when needed

Detailed Evidence

Put detailed logs, command output, and review chains in:

  • docs/agent_ops/OUTBOX/
  • SSOT docs
  • task specs / ADRs

Use the KG for durable summaries, not raw evidence dumps.