Smriti

State-aware Memory Runtime for Intelligent Temporal Inference

Smriti is the decision-grade memory runtime for coding agents. The repo has been cleaned down to a Phase 0-1 architecture: tenant-safe control-plane infrastructure plus a trace-native write path that future event segmentation, transfer-aware recall, and audited action advice will build on.

What Exists Today

• Hardened customer and API-key management
• Tenant-scoped quota accounting and audit logging
• Append-only trace ingestion at POST /api/v2/trace/append
• Trace replay at GET /api/v2/trace/{trace_id}
• Trace finalization at POST /api/v2/trace/{trace_id}/finalize
• Canonical SQLite tables for traces, event_frames, schemas, skills, graph_*, memory_feedback, personal_memory, and quarantined_memory
• Optional KyroDB connectivity preserved for future retrieval/graph phases

Architectural Baseline

The repo does not treat Episode, Reflection, failure-only search, cached reflection tiers, or heuristic gating as the architectural truth. The codebase centers on the cleaned trace-native runtime and builds forward from there.

Source Of Truth

Read these in order:

1. AGENTS.md
2. other_docs/SMRITI_Implementation_PLAN.md
3. docs/ARCHITECTURE.md
4. docs/API_GUIDE.md

These documents use the current product naming: Smriti outside and SMRITI inside.

Quick Start

pip install -r requirements.txt
cp .env.production.example .env
uvicorn src.main:app --reload --port 8000

The service targets Python 3.11.

Bootstrap A Tenant

Create a customer and an API key:

curl -X POST http://localhost:8000/api/customers \
  -H "X-Admin-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "acme-dev",
    "organization_name": "Acme Dev",
    "email": "platform@acme.dev",
    "subscription_tier": "free"
  }'

curl -X POST http://localhost:8000/api/customers/acme-dev/api-keys \
  -H "X-Admin-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "codex"}'

Append A Trace

curl -X POST http://localhost:8000/api/v2/trace/append \
  -H "X-API-Key: em_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "deploy-prod-001",
    "agent_id": "codex",
    "session_id": "session-42",
    "task_id": "deploy-production",
    "steps": [
      {
        "step_idx": 0,
        "ts": "2026-04-17T12:00:00Z",
        "tool_call_json": {"tool": "shell", "cmd": "kubectl apply -f deployment.yaml"},
        "tool_result_json": {"exit_code": 1, "stderr": "ImagePullBackOff"},
        "state_snapshot_json": {"cluster": "production", "service": "payments"},
        "error_signature": "kubernetes:image-pull-back-off",
        "privacy_tags": ["terminal"],
        "source_trust": 0.98
      }
    ]
  }'

Finalize the trace once the attempt is complete:

curl -X POST http://localhost:8000/api/v2/trace/deploy-prod-001/finalize \
  -H "X-API-Key: em_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "final_step_idx": 0,
    "outcome": "failure",
    "summary_json": {"result": "image missing in registry"}
  }'

Development

pytest tests/ -v
black src/ tests/
ruff check src/ tests/
mypy src/