Agentic Shared Project Memory

An evidence-backed agentic system for distributed engineering handoffs. It uses separate synthesis and review agents to turn bounded engineering activity into reviewable, evidence-linked project memory—without allowing generated output to silently become project truth.

Agentic workflow

The app has two separate, versioned agents:

• Activity Synthesizer creates source-linked handoff drafts and surfaces omitted activity.
• Evidence Reviewer challenges claims and proposes—never applies—knowledge-state relationships.

agent_runtime.py loads these contracts into provider-neutral structured requests. The Activity Synthesizer and Evidence Reviewer are independent agent roles; neither has canonical-memory write authority.

Codex plugin

The repository includes an installable, pre-submission Codex plugin in plugins/shared-project-memory. Its handoff skill captures privacy-bounded local Git evidence, drafts a handoff, and invokes the Evidence Reviewer before any database submission. It never uploads a transcript or writes to Agentic Shared Project Memory by itself.

Run locally

Requires Python 3.11+ only.

python3 app.py

The first run creates project-memory.db and seeds the timezone-handoff demo.

For a repeatable walkthrough, follow the product demo runbook. For deployment boundaries, required configuration, and the remaining release gates, see operational readiness.

What is implemented

• Engineer handoff workspace with activity reconstruction, manual notes, reviewer findings, and submit/attest.
• Lead approval queue for individual claims and decisions.
• Evidence detail, immutable audit trail, direct contradiction/supersession relationships.
• Lead correction API that appends a replacement item, preserves cited evidence, and marks the old item superseded.
• Cited manager status briefing.
• MCP-shaped, authenticated-in-production API routes (demo actor identity is selected in the UI):
  • GET /api/mcp/handoff-context
  • GET /api/mcp/search
  • GET /api/mcp/item-evidence?id=...
• GET /api/mcp/architecture-context?scope=...
• A standards-compatible stdio MCP adapter: python3 mcp_server.py
• GitHub adapter boundary. Set GITHUB_TOKEN, GITHUB_OWNER, and GITHUB_REPO to enable real source retrieval; the demo otherwise uses seeded source records.

Connected handoff configuration

Copy .env.example into your deployment’s secret store; do not commit credentials. For local use, the app reads a git-ignored .env file without logging its values; process environment variables take precedence. All external calls are opt-in.

• POST /api/source-refresh performs an explicit, read-only GitHub fetch for the handoff window. It imports commit metadata, PRs, reviews, and changed paths; it does not import full diffs or CI logs.
• POST /api/agent-runs with {"agent_name":"activity-synthesizer"} or {"agent_name":"evidence-reviewer"} runs the corresponding versioned agent.md contract through the configured model endpoint.
• Agent inputs, contract hashes, outputs, latency, and failures are stored in append-only agent_runs. Invalid or unavailable model responses create an auditable failed run and no memory item.

The model adapter requires an endpoint, API key, and named model. The application sends only the selected handoff sources, author notes, and—for review—bounded relevant approved memory. Run the offline demo without these values; configure them only when demonstrating live agent runs.

Production notes

schema/postgres.sql is the authoritative PostgreSQL + pgvector data model. The local demo uses SQLite with equivalent core entities and constraints. Before deployment, put the app behind TLS, replace demo identity headers with GitHub OAuth device-flow verification, use managed PostgreSQL/object storage, and configure the approved model endpoint for synthesis/review.

The checked-in source timeline is deterministic demo data, including commits, PR/reviews, CI, and a repository document. Real GitHub ingestion is explicit and read-only; configure it with a least-privilege GitHub App installation token in production.

The local application deliberately uses a selectable demo actor and SQLite. Do not expose it to an untrusted network or treat it as a production authentication or authorization implementation.

Verification

python3 -m unittest discover -s tests -v
python3 scripts/check_demo_readiness.py