# suraj-ranganath/scopememory architecture

> Architecture diagram of the GitHub repository suraj-ranganath/scopememory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suraj-ranganath/scopememory
- Repository: https://github.com/suraj-ranganath/scopememory

## Overview

1. **What this repository is**
   - ScopeMemory is an authorization control plane for long-horizon agents: it predicts likely tool use, scopes permissions narrowly, and records the decision trail.
   - The repo is split between a small dependency-free demo and a more complete platform prototype.

2. **Two main execution paths**
   - `demo/` is the simplest end-to-end proof: a SQLite-backed terminal demo that shows the ReBAC/authorization concept without infrastructure.
   - `platform/` is the real architecture prototype: FastAPI/Uvicorn services, graph backends, policy evaluation, credential brokering, MCP integration, and review UIs.

3. **Canonical state and audit**
   - Dolt is the authoritative store for governed memory: workflow recipes, grants, policy state, graph edges, and audit/proof records.
   - The architectural intent is that authorization changes are versioned and reviewable like code, which is why the repo emphasizes branch/diff/replay semantics.

4. **Context graph and derived retrieval**
   - The platform builds a shared context graph from sessions, tools, scopes, resources, teams, approvals, and recipes.
   - `memgraph_sync.py`, `graph_backend.py`, and `graph_fallback.py` indicate a derived graph layer for traversal and a local fallback when the graph service is unavailable.
   - `person_b/` adds recipe indexing and learning-oriented fixtures, suggesting a memory-retrieval subsystem that turns prior workflows into candidate authorization facts.

5. **Policy decision boundary**
   - Policy is not embedded in the agent; it is evaluated centrally through Datalog-style logic (`cozo_policy.py`, `policy_contracts.py`, `authorization_checks.py`).
   - The decision model is explicit: allow, ephemeral auto-approve, escalate to human, deny, or repair malformed requests.
   - The important architecture boundary is that candidate context can be proposed by retrieval/LLM systems, but the final decision is policy-driven and reproducible.

6. **Identity and delegation**
   - `platform/agentic_identity/` handles signed delegation JWTs and the IAM adapter that binds user/team/agent identity into the authorization chain.
   - This is the trust anchor that lets the gateway reason about “who delegated to which agent for which workflow,” rather than relying on broad standing credentials.

7. **Credential brokering and secret containment**
   - `credential_broker.py`, `credential_runtime.py`, `onepassword_provider.py`, and `onepassword_readiness.py` show a brokered secret path.
   - The intended pattern is opaque credential leases: the agent never sees decrypted secrets; they are injected only inside the execution boundary.
   - `hook_adapter.py` and `codex_hook.py` indicate pre-tool-call interception for Claude/Codex-style runtimes, so secret-bearing actions can be normalized and gated before execution.

8. **MCP is the external tool boundary**
   - `platform/mcp/` is a standalone JSON-RPC/MCP server layer with routing, handlers, registry, visibility, and safe views.
   - This is the main enforcement surface for tools: the gateway can inspect a tool request, preflight it, authorize it, and then allow the MCP call to proceed with scoped permissions.

9. **Gateway-centric control flow**
   - `gateway_service.py`, `platform/app.py`, and related modules implement the runtime that sits between agents and tools.
   - The flow is: agent host sends an MCP/tool request → gateway resolves identity and context graph → policy evaluates against governed state → gateway either blocks, escalates, repairs, or issues a narrow grant/lease → execution occurs → audit is written back to canonical storage.

10. **UI and operator surfaces**
   - `platform/web/` is a React/Vite frontend for reviewing requests, proofs, and workflow state.
   - `platform/streamlit_app.py` and `platform/ui/` provide a lighter policy console / demo UI path.
   - These are read-mostly operational surfaces over the same governed state, not separate sources of truth.

11. **Learning and demo-specific memory**
   - `platform/person_b/` contains a focused “learning worker,” contract fixtures, and recipe fixtures for demonstrating how past access requests become future authorization memory.
   - This subsystem looks like the experimentation zone for recipe proposal, indexing, and session-driven memory shaping.

12. **Infrastructure and repo organization**
   - The platform is packaged for local orchestration with `docker-compose.yml`, a `Dockerfile`, and `run_stack.sh`.
   - The docs in `docs/engineering-plan/` are a first-class architectural artifact: they define the RFCs, research, decisions, and roadmap that govern the code.
   - For an architecture diagram, the key boxes are: agent host, identity, gateway, context graph, policy engine, Dolt, graph store/fallback, credential broker, MCP server, and review UI, with audit flowing back into Dolt.

Main entry points: [`platform/gateway_service.py`](https://github.com/suraj-ranganath/scopememory/blob/main/platform/gateway_service.py) (Gateway), [`platform/graph_backend.py`](https://github.com/suraj-ranganath/scopememory/blob/main/platform/graph_backend.py) (Context graph), [`platform/cozo_policy.py`](https://github.com/suraj-ranganath/scopememory/blob/main/platform/cozo_policy.py) (Policy engine), [`platform/dolt_store.py`](https://github.com/suraj-ranganath/scopememory/blob/main/platform/dolt_store.py) (Dolt store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Demo path"]
  node_demo_terminal["Demo demo<br/>sqlite terminal demo<br/>[run_demo.py]"]
  node_demo_rebac["ReBAC logic<br/>authorization rules<br/>[rebac.py]"]
end

subgraph group_core["Control plane"]
  node_platform_app["App entry<br/>FastAPI app<br/>[app.py]"]
  node_gateway_service["Gateway<br/>[gateway_service.py]"]
  node_identity["Identity<br/>delegation IAM"]
  node_policy["Policy engine<br/>decision logic<br/>[cozo_policy.py]"]
  node_auth_checks["Auth checks<br/>validation layer"]
  node_grant_lifecycle["Grant lifecycle<br/>grant state<br/>[grant_lifecycle.py]"]
  node_runtime_exec["Runtime exec<br/>execution boundary"]
end

subgraph group_data["Governed state"]
  node_dolt_store[("Dolt store<br/>versioned source<br/>[dolt_store.py]")]
  node_dolt_schema["Dolt schema<br/>schema + init<br/>[schema.sql]"]
  node_context_graph{{"Context graph<br/>derived graph<br/>[graph_backend.py]"}}
  node_graph_sync["Graph sync<br/>graph ingestion<br/>[memgraph_sync.py]"]
  node_graph_fallback["Graph fallback<br/>local graph<br/>[graph_fallback.py]"]
end

subgraph group_tools["Tool boundary"]
  node_mcp_server["MCP server<br/>tool server<br/>[server.py]"]
  node_credential_broker["Credential broker<br/>secret lease"]
  node_hook_adapter["Hook adapter<br/>runtime hook<br/>[hook_adapter.py]"]
end

subgraph group_ops["Operator surfaces"]
  node_web_ui["Web UI<br/>React review UI<br/>[App.tsx]"]
  node_streamlit_ui["Policy console<br/>Streamlit UI<br/>[streamlit_app.py]"]
end

subgraph group_learn["Learning"]
  node_learning_worker["Learning worker<br/>memory indexer<br/>[learning_worker.py]"]
  node_recipe_index["Recipe index<br/>recipe retrieval"]
end

subgraph group_docs["Architecture docs"]
  node_engineering_plan["RFCs<br/>architecture docs<br/>[README.md]"]
end

node_demo_terminal -->|"uses"| node_demo_rebac
node_platform_app -->|"hosts"| node_gateway_service
node_gateway_service -->|"resolves"| node_identity
node_gateway_service -->|"loads context"| node_context_graph
node_gateway_service -->|"evaluates"| node_policy
node_gateway_service -->|"validates"| node_auth_checks
node_gateway_service -->|"issues grant"| node_grant_lifecycle
node_grant_lifecycle -->|"permits"| node_runtime_exec
node_runtime_exec -->|"leases secrets"| node_credential_broker
node_credential_broker -->|"attaches to"| node_hook_adapter
node_hook_adapter -->|"gates calls"| node_mcp_server
node_gateway_service -->|"fronts"| node_mcp_server
node_dolt_store -->|"defines"| node_dolt_schema
node_policy -->|"reads state"| node_dolt_store
node_context_graph -->|"built by"| node_graph_sync
node_context_graph -->|"falls back to"| node_graph_fallback
node_graph_sync -->|"syncs from"| node_dolt_store
node_learning_worker -->|"builds"| node_recipe_index
node_learning_worker -->|"proposes facts"| node_context_graph
node_web_ui -->|"reviews"| node_dolt_store
node_streamlit_ui -->|"operates"| node_policy
node_engineering_plan -.->|"specifies"| node_gateway_service
node_engineering_plan -.->|"specifies"| node_policy
node_engineering_plan -.->|"specifies"| node_credential_broker

click node_demo_terminal "https://github.com/suraj-ranganath/scopememory/blob/main/demo/run_demo.py"
click node_demo_rebac "https://github.com/suraj-ranganath/scopememory/blob/main/demo/rebac.py"
click node_platform_app "https://github.com/suraj-ranganath/scopememory/blob/main/platform/app.py"
click node_gateway_service "https://github.com/suraj-ranganath/scopememory/blob/main/platform/gateway_service.py"
click node_identity "https://github.com/suraj-ranganath/scopememory/tree/main/platform/agentic_identity"
click node_policy "https://github.com/suraj-ranganath/scopememory/blob/main/platform/cozo_policy.py"
click node_auth_checks "https://github.com/suraj-ranganath/scopememory/blob/main/platform/authorization_checks.py"
click node_grant_lifecycle "https://github.com/suraj-ranganath/scopememory/blob/main/platform/grant_lifecycle.py"
click node_runtime_exec "https://github.com/suraj-ranganath/scopememory/blob/main/platform/runtime_execution.py"
click node_dolt_store "https://github.com/suraj-ranganath/scopememory/blob/main/platform/dolt_store.py"
click node_dolt_schema "https://github.com/suraj-ranganath/scopememory/blob/main/platform/dolt/schema.sql"
click node_context_graph "https://github.com/suraj-ranganath/scopememory/blob/main/platform/graph_backend.py"
click node_graph_sync "https://github.com/suraj-ranganath/scopememory/blob/main/platform/memgraph_sync.py"
click node_graph_fallback "https://github.com/suraj-ranganath/scopememory/blob/main/platform/graph_fallback.py"
click node_mcp_server "https://github.com/suraj-ranganath/scopememory/blob/main/platform/mcp/server.py"
click node_credential_broker "https://github.com/suraj-ranganath/scopememory/blob/main/platform/credential_broker.py"
click node_hook_adapter "https://github.com/suraj-ranganath/scopememory/blob/main/platform/hook_adapter.py"
click node_web_ui "https://github.com/suraj-ranganath/scopememory/blob/main/platform/web/src/App.tsx"
click node_streamlit_ui "https://github.com/suraj-ranganath/scopememory/blob/main/platform/streamlit_app.py"
click node_learning_worker "https://github.com/suraj-ranganath/scopememory/blob/main/platform/person_b/learning_worker.py"
click node_recipe_index "https://github.com/suraj-ranganath/scopememory/blob/main/platform/person_b/memgraph_recipe_index.py"
click node_engineering_plan "https://github.com/suraj-ranganath/scopememory/blob/main/docs/engineering-plan/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_demo_terminal,node_demo_rebac,node_engineering_plan toneBlue
class node_platform_app,node_gateway_service,node_identity,node_policy,node_auth_checks,node_grant_lifecycle,node_runtime_exec toneAmber
class node_dolt_store,node_dolt_schema,node_context_graph,node_graph_sync,node_graph_fallback toneMint
class node_mcp_server,node_credential_broker,node_hook_adapter toneRose
class node_web_ui,node_streamlit_ui toneIndigo
class node_learning_worker,node_recipe_index toneTeal
```

## Components

### Demo path

Dependency-free end-to-end authorization proof

- [Demo demo](https://github.com/suraj-ranganath/scopememory/blob/main/demo/run_demo.py): sqlite terminal demo · Minimal SQLite-backed ReBAC proof-of-concept · `demo/run_demo.py`
- [ReBAC logic](https://github.com/suraj-ranganath/scopememory/blob/main/demo/rebac.py): authorization rules · Tiny demo authorization model and checks · `demo/rebac.py`

### Control plane

Gateway, identity, policy, and execution runtime

- [App entry](https://github.com/suraj-ranganath/scopememory/blob/main/platform/app.py): FastAPI app · Main platform service entrypoint · `platform/app.py`
- [Gateway](https://github.com/suraj-ranganath/scopememory/blob/main/platform/gateway_service.py): request gateway · Sits between agent hosts and tools · `platform/gateway_service.py`
- [Identity](https://github.com/suraj-ranganath/scopememory/tree/main/platform/agentic_identity): delegation IAM · Signed delegation and IAM binding for user/team/agent identity · `platform/agentic_identity`
- [Policy engine](https://github.com/suraj-ranganath/scopememory/blob/main/platform/cozo_policy.py): decision logic · Central allow/deny/escalate/repair evaluation · `platform/cozo_policy.py`
- [Auth checks](https://github.com/suraj-ranganath/scopememory/blob/main/platform/authorization_checks.py): validation layer · Authorization request validation and policy gating helpers · `platform/authorization_checks.py`
- [Grant lifecycle](https://github.com/suraj-ranganath/scopememory/blob/main/platform/grant_lifecycle.py): grant state · Narrow grant and lease issuance across request flow · `platform/grant_lifecycle.py`
- [Runtime exec](https://github.com/suraj-ranganath/scopememory/blob/main/platform/runtime_execution.py): execution boundary · Executes approved actions inside constrained runtime · `platform/runtime_execution.py`

### Governed state

Canonical storage and derived graph layer

- [Dolt store](https://github.com/suraj-ranganath/scopememory/blob/main/platform/dolt_store.py): versioned source · Canonical governed memory, policy state, grants, and audit trail · `platform/dolt_store.py`
- [Dolt schema](https://github.com/suraj-ranganath/scopememory/blob/main/platform/dolt/schema.sql): schema + init · Authoritative tables and initialization for governed state · `platform/dolt/schema.sql`
- [Context graph](https://github.com/suraj-ranganath/scopememory/blob/main/platform/graph_backend.py): derived graph · Shared graph of sessions, tools, scopes, resources, teams, and approvals · `platform/graph_backend.py`
- [Graph sync](https://github.com/suraj-ranganath/scopememory/blob/main/platform/memgraph_sync.py): graph ingestion · Syncs governed state into Memgraph-style derived views · `platform/memgraph_sync.py`
- [Graph fallback](https://github.com/suraj-ranganath/scopememory/blob/main/platform/graph_fallback.py): local graph · Local traversal fallback when graph service is unavailable · `platform/graph_fallback.py`

### Tool boundary

MCP and credential containment

- [MCP server](https://github.com/suraj-ranganath/scopememory/blob/main/platform/mcp/server.py): tool server · JSON-RPC/MCP surface for external tools · `platform/mcp/server.py`
- [Credential broker](https://github.com/suraj-ranganath/scopememory/blob/main/platform/credential_broker.py): secret lease · Opaque secret injection and lease handling · `platform/credential_broker.py`
- [Hook adapter](https://github.com/suraj-ranganath/scopememory/blob/main/platform/hook_adapter.py): runtime hook · Pre-tool-call interception and normalization for agent runtimes · `platform/hook_adapter.py`

### Operator surfaces

Human review and console UIs

- [Web UI](https://github.com/suraj-ranganath/scopememory/blob/main/platform/web/src/App.tsx): React review UI · Browser interface for requests, proofs, and workflow state · `platform/web/src/App.tsx`
- [Policy console](https://github.com/suraj-ranganath/scopememory/blob/main/platform/streamlit_app.py): Streamlit UI · Lightweight operator console for policy and demo flows · `platform/streamlit_app.py`

### Learning

Recipe indexing and memory shaping

- [Learning worker](https://github.com/suraj-ranganath/scopememory/blob/main/platform/person_b/learning_worker.py): memory indexer · Transforms past access into candidate authorization memory · `platform/person_b/learning_worker.py`
- [Recipe index](https://github.com/suraj-ranganath/scopememory/blob/main/platform/person_b/memgraph_recipe_index.py): recipe retrieval · Indexes recipe and recipe-hit fixtures for future decisions · `platform/person_b/memgraph_recipe_index.py`

### Architecture docs

RFCs and engineering plan

- [RFCs](https://github.com/suraj-ranganath/scopememory/blob/main/docs/engineering-plan/README.md): architecture docs · First-class engineering plan, decisions, and roadmap · `docs/engineering-plan/README.md`

## Connections

- Demo demo → ReBAC logic: uses · The terminal demo exercises the demo authorization model
- App entry → Gateway: hosts · The platform entrypoint runs the gateway-centric runtime
- Gateway → Identity: resolves · Gateway binds user/team/agent identity before decisions
- Gateway → Context graph: loads context · Gateway consults the shared context graph for requests
- Gateway → Policy engine: evaluates · Central policy decides allow, escalate, deny, or repair
- Gateway → Auth checks: validates · Request shaping and authorization checks happen before grant
- Gateway → Grant lifecycle: issues grant · Gateway can create narrow grants or leases
- Grant lifecycle → Runtime exec: permits · Approved grants constrain execution
- Runtime exec → Credential broker: leases secrets · Secrets are injected inside the execution boundary
- Credential broker → Hook adapter: attaches to · Hooks intercept secret-bearing tool calls before execution
- Hook adapter → MCP server: gates calls · Normalized tool requests are forwarded to MCP
- Gateway → MCP server: fronts · Gateway is the enforcement surface before MCP tool access
- Dolt store → Dolt schema: defines · Schema establishes the canonical governed store
- Policy engine → Dolt store: reads state · Policy evaluation uses versioned governed memory
- Context graph → Graph sync: built by · Derived graph is kept in sync from governed state
- Context graph → Graph fallback: falls back to · Local graph traversal is used when the main service is unavailable
- Graph sync → Dolt store: syncs from · Graph ingestion derives from canonical storage
- Learning worker → Recipe index: builds · Learning worker indexes access and recipe fixtures
- Learning worker → Context graph: proposes facts · Learning feeds candidate memory into the shared graph
- Web UI → Dolt store: reviews · Review UI reads governed state and audit trails
- Policy console → Policy engine: operates · Console surfaces policy decisions and demo flows
- RFCs → Gateway: specifies · RFCs define the gateway-centric architecture
- RFCs → Policy engine: specifies · Docs define the policy and proof model
- RFCs → Credential broker: specifies · Docs define credential containment and hook behavior