How harshitk-cp/engram works
1. Repository shape
This is a Go backend centered on an AI memory service. It ships two runnable entry points: cmd/server for the HTTP API + admin console, and cmd/engram-mcp for a standalone MCP server. The same core packages are reused by both.
2. Top-level runtime boundary
The main production boundary is the HTTP server. Requests enter through internal/api/router.go, pass through middleware, then dispatch to handler packages under internal/api/handlers, which call into internal/service. The MCP binary is a separate transport layer that exposes the same capabilities as tools instead of REST endpoints.
3. Layering
The backend is organized in a fairly classic hexagonal style:
- internal/api = transport, auth, rate limiting, quotas, request shaping
- internal/service = business logic and memory algorithms
- internal/store = persistence and transaction/unit-of-work boundaries
- internal/domain = core entities and value logic
- internal/llm and internal/embedding = external AI provider adapters
4. Core data path
Memory writes and reads flow from API/MCP into the service layer, then into PostgreSQL via the store layer. The service layer performs the domain-specific work: confidence updates, contradiction handling, consolidation, decay, recall ranking, and working-memory activation before data is persisted or returned.
5. Cognitive core
The distinctive subsystem is the “cognitive core” implemented in internal/service: semantic memories, episodic memories, procedural memories, working memory, schemas, metacognition, calibration, decay, and hybrid recall. These are not separate services; they are coordinated behaviors over the same database-backed model.
6. Provenance Firewall and quarantine
Untrusted or externally extracted knowledge is not immediately treated as canonical. The codebase has a dedicated quarantine/review path in the API and service layers, with release/reject flows and audit logging. This is a hard boundary between raw ingestion and trusted memory.
7. Audit and trust model
A major subsystem is the append-only audit chain. The README and migrations show a tamper-evident SHA-256 hash chain, audit verification/export endpoints, and mutation logging for every belief change. This means memory state is not just stored; its evolution is recorded as a verifiable history.
8. Multi-subject isolation
The domain supports multiple “bindings” for the same agent: private, anchored, session, and canon. Anchors represent subject-level isolation, sessions represent short-lived conversational context, and canon represents tenant-wide shared knowledge. This isolation is enforced in the service/store layer and reflected in endpoints for anchors, sessions, and canon.
9. Persistence model
PostgreSQL is the primary datastore, with pgvector support implied by the README and migrations. The migrations directory shows the schema evolving to support embeddings, graph retrieval, API keys, audit chain, tenant isolation, quarantine, billing, and tuning settings. The data model is therefore both relational and vector-enabled.
10. Retrieval architecture
Recall is hybrid: vector similarity plus graph traversal. The service layer combines entity/graph data from internal/store/graph.go with embedding-backed search, then returns scored results with provenance. This is the main read path for agent context injection.
11. External integrations
The code abstracts several external systems behind provider packages:
- LLM providers: OpenAI, Anthropic, Gemini, Cerebras, plus mock/none modes
- Embeddings: provider interface plus compatibility/mocks
- Billing: Razorpay integration, enabled only when keys are configured
These are optional adapters; the core system still functions in embedding-only or no-LLM modes.
12. Admin console
The React console under console/ is built with Vite and embedded into the Go binary (console/embed.go). It is not a separate deployment requirement. The console is an operator surface for agents, memories, contradictions, quarantine, audit, keys, billing, settings, and time-travel inspection.
13. MCP surface
The mcp/ package and cmd/engram-mcp expose the same memory system as MCP tools over stdio, HTTP, or SSE transports. This is a separate integration boundary for agent hosts like Claude Desktop or Cursor, but it reuses the same underlying business logic.
14. Operational concerns
Middleware handles auth, CORS, logging, request IDs, metrics, rate limiting, and quota enforcement. Configuration lives in internal/config and internal/buildconfig, and deployment is containerized via Dockerfile, docker-compose.yml, and migration scripts. The architecture is therefore a single Go service with multiple interfaces, backed by PostgreSQL and enriched by optional AI and billing providers.
Main entry points: service Service Core · router.go Router · store Store · main.go Server
Components 20
Runtimes
Runnable entry points and transport surfaces
- Server · Main production binary for the API and admin console
cmd/server/main.go - MCP Server · Standalone binary exposing memory tools over MCP transports
cmd/engram-mcp/main.go - Router · HTTP route registration and request dispatch
internal/api/router.go - Middleware · Auth, CORS, logging, metrics, quotas, and rate limits
internal/api/middleware - Handlers · API endpoints for memories, agents, audit, quarantine, and admin flows
internal/api/handlers - MCP Tools · Shared memory capabilities exposed as MCP resources and tools
mcp
Core Layers
Shared business logic and persistence boundaries
- Service Core · Central memory orchestration and cognitive behaviors
internal/service - Domain Model · Core entities, bindings, policies, memories, and settings
internal/domain - Store · Database access and unit-of-work boundaries
internal/store - Cognitive Core · Semantic, episodic, procedural, working-memory, metacognition, decay, and consolidation behaviors
internal/service - Hybrid Recall · Vector similarity plus graph traversal with provenance-ranked results
internal/service/hybrid_recall.go - Provenance Firewall · Quarantine, review, release, reject, and audit-gated ingestion path
internal/service/contradiction - Audit Chain · Mutation logging and SHA-256 hash-chain verification of memory changes
internal/store - Trust & Auth · API keys, tenants, sessions, anchors, and access control
internal/api/middleware/auth.go - Config · Runtime and build configuration
internal/config
Integrations
External AI, billing, and transport adapters
- LLM Adapters · OpenAI, Anthropic, Gemini, Cerebras, mock, and none modes
internal/llm - Embeddings · Embedding provider interface and compatibility mocks
internal/embedding - Billing · Razorpay integration for tenant billing and plan state
internal/billing/razorpay.go
Console
Embedded operator interface
- Console UI · Embedded operator console for memories, audit, quarantine, keys, billing, and settings
console/src/App.tsx - Embed Console · Build-time embedding of the React console into the Go binary
console/embed.go
Connections 23
- Server → Router: starts · Server boots the HTTP router
- Server → Embed Console: serves UI · Server includes the embedded console assets
- MCP Server → MCP Tools: starts · Standalone binary exposes MCP surface
- Router → Middleware: wraps · Router applies cross-cutting request middleware
- Router → Handlers: dispatches · Routes map to API handlers
- Handlers → Service Core: calls · Handlers delegate to business logic
- MCP Tools → Service Core: invokes · MCP tools reuse the same service layer
- Service Core → Cognitive Core: orchestrates · Service layer coordinates memory behaviors
- Service Core → Hybrid Recall: queries · Service performs hybrid recall for context injection
- Service Core → Provenance Firewall: routes · Untrusted knowledge enters quarantine and review flows
- Service Core → Audit Chain: records · Memory mutations are appended to the audit chain
- Service Core → Store: persists · Business logic writes and reads through the store
- Service Core → Domain Model: models · Service logic operates on domain entities and value rules
- Store → Domain Model: maps · Persistence follows the core domain model
- Store → Audit Chain: writes · Store layer participates in mutation logging and verification
- Service Core → LLM Adapters: uses · Optional LLM-backed classification and reasoning
- Service Core → Embeddings: uses · Embedding-backed similarity and retrieval support
- Service Core → Billing: checks · Billing state gates quota and tenant behavior
- Middleware → Trust & Auth: enforces · Request middleware applies auth, quotas, and tenant controls
- Config → Server: configures · Configuration drives server startup and feature flags
- Config → MCP Server: configures · Configuration drives MCP startup and transport selection
- Console UI → Handlers: calls · Console interacts with the HTTP API
- Embed Console → Console UI: packages · Console is embedded into the Go binary