suraj-ranganath/scopememory

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.