{"id":35218200,"url":"https://github.com/rawcontext/engram","last_synced_at":"2026-01-13T21:42:25.217Z","repository":{"id":331383260,"uuid":"1124390993","full_name":"rawcontext/engram","owner":"rawcontext","description":"A bitemporal, graph-backed memory system for AI coding agents.","archived":false,"fork":false,"pushed_at":"2026-01-05T20:10:48.000Z","size":24704,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-07T07:49:16.684Z","etag":null,"topics":["agent-orchestration","ai-agents","bitemporal","context-graph","developer-tools","knowledge-graph","observability","vector-search"],"latest_commit_sha":null,"homepage":"https://rawcontext.com/projects/engram/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rawcontext.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-29T00:01:54.000Z","updated_at":"2026-01-05T20:10:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rawcontext/engram","commit_stats":null,"previous_names":["rawcontext/engram"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/rawcontext/engram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawcontext%2Fengram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawcontext%2Fengram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawcontext%2Fengram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawcontext%2Fengram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rawcontext","download_url":"https://codeload.github.com/rawcontext/engram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawcontext%2Fengram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28401058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","ai-agents","bitemporal","context-graph","developer-tools","knowledge-graph","observability","vector-search"],"created_at":"2025-12-29T23:03:12.151Z","updated_at":"2026-01-13T21:42:25.206Z","avatar_url":"https://github.com/rawcontext.png","language":"TypeScript","readme":"# Engram\n\nBitemporal, graph-backed memory system for AI coding agents. Captures reasoning traces from Claude Code, Codex CLI, and others into a knowledge graph with full temporal history.\n\n[engram_preview.webm](https://github.com/user-attachments/assets/f869ee5a-5f45-4d84-a33c-757e3d17276d)\n\n## Quick Start\n\n```bash\n# Prerequisites: Bun v1.3.5+, Docker, Python 3.12+ with uv\n\ngit clone https://github.com/ccheney/engram.git\ncd engram\nbun install\nbun run infra:up   # Start FalkorDB, Qdrant, NATS, PostgreSQL\nbun run dev        # Start all services\n```\n\n**Verify**: Observatory http://localhost:6178 | API http://localhost:6174/v1/health\n\n## Architecture\n\n```\nCLI Agents → Ingestion (6175) → NATS → Memory → FalkorDB\n                                    ↓\n                              Search (6176) → Qdrant\n                                    ↓\n                           Neural Observatory (6178)\n```\n\n**Storage**: FalkorDB (graph), Qdrant (vectors), NATS+JetStream (events), PostgreSQL (API keys/usage)\n\n**Bitemporal**: All graph nodes track `vt_start/vt_end` (valid time) and `tt_start/tt_end` (transaction time) for time-travel queries.\n\n## Project Structure\n\n### Applications\n\n| App | Port | Purpose |\n|-----|------|---------|\n| [api](apps/api) | 6174 | REST API - memory ops, OAuth, rate limiting, OpenTofu state backend |\n| [ingestion](apps/ingestion) | 6175 | Event parsing from 8+ providers, PII redaction |\n| [mcp](apps/mcp) | stdio | MCP server - remember/recall/query/context tools |\n| [memory](apps/memory) | - | Graph persistence, turn aggregation, NATS consumer |\n| [observatory](apps/observatory) | 6178 | Next.js 16 real-time session visualization |\n| [console](apps/console) | 6185 | Next.js 16 infrastructure management console |\n| [search](apps/search) | 6176 | Python/FastAPI hybrid search, multi-tier reranking |\n| [tuner](apps/tuner) | 6177 | Python/FastAPI Optuna hyperparameter optimization |\n\n### Packages\n\n| Package | Purpose |\n|---------|---------|\n| [benchmark](packages/benchmark) | LongMemEval/MTEB/BEIR evaluation suite (Python) |\n| [common](packages/common) | Utilities, errors, constants, test fixtures |\n| [engram-plugin](packages/engram-plugin) | Claude Code plugin for memory commands |\n| [events](packages/events) | Zod schemas for RawStreamEvent/ParsedStreamEvent |\n| [graph](packages/graph) | Bitemporal models, repositories, QueryBuilder |\n| [infra](packages/infra) | OpenTofu IaC for Hetzner Cloud deployment |\n| [logger](packages/logger) | Pino structured logging with PII redaction |\n| [parser](packages/parser) | Provider parsers, extractors, redaction |\n| [storage](packages/storage) | FalkorDB, NATS, PostgreSQL, Redis, blob clients |\n| [temporal](packages/temporal) | Rehydrator, TimeTravelService, ReplayEngine |\n| [tsconfig](packages/tsconfig) | Shared TypeScript 7 configuration |\n| [tuner](packages/tuner) | TypeScript client/CLI for tuner service |\n| [vfs](packages/vfs) | VirtualFileSystem, NodeFileSystem, PatchManager |\n\n## Commands\n\n```bash\n# Development\nbun run dev          # Start all services\nbun run infra:up     # Start infrastructure (Docker)\nbun run infra:down   # Stop infrastructure\n\n# Build \u0026 Test\nbun run build        # Build all packages\nbun run test         # Run Vitest tests\nbun run typecheck    # TypeScript validation\nbun run lint         # Biome linting\nbun run format       # Biome formatting\n\n# Python services\ncd apps/search \u0026\u0026 uv sync \u0026\u0026 uv run search\ncd apps/tuner \u0026\u0026 uv sync \u0026\u0026 uv run tuner\n```\n\n## MCP Tools\n\n| Tool | Purpose |\n|------|---------|\n| `remember` | Store memory with type (decision/insight/preference/fact) and tags |\n| `recall` | Retrieve memories via hybrid semantic/keyword search |\n| `query` | Execute read-only Cypher queries (local mode) |\n| `context` | Comprehensive context assembly for tasks (local mode) |\n| `summarize` | Condense text using client LLM (requires sampling) |\n| `extract_facts` | Parse text into atomic facts (requires sampling) |\n| `enrich_memory` | Auto-generate summary/keywords/category (requires sampling) |\n\n## API Endpoints\n\n| Endpoint | Method | Scope | Purpose |\n|----------|--------|-------|---------|\n| `/v1/health` | GET | Public | Health check |\n| `/v1/memory/remember` | POST | `memory:write` | Store memory with deduplication |\n| `/v1/memory/recall` | POST | `memory:read` | Hybrid search with reranking |\n| `/v1/memory/query` | POST | `query:read` | Read-only Cypher queries |\n| `/v1/memory/context` | POST | `memory:read` | Context assembly |\n| `/v1/tofu` | GET/POST | `state:write` | OpenTofu remote state |\n\n## Providers\n\nIngestion supports 8+ LLM providers:\n\n| Provider | Key | Aliases |\n|----------|-----|---------|\n| Anthropic | `anthropic` | `claude` |\n| OpenAI | `openai` | `gpt`, `gpt-4` |\n| Google Gemini | `gemini` | - |\n| XAI (Grok) | `xai` | `grok` |\n| Claude Code | `claude_code` | `claude-code` |\n| Cline | `cline` | - |\n| Codex | `codex` | - |\n| OpenCode | `opencode` | - |\n\n## Infrastructure\n\nAll services use Kaprekar's constant (6174) as the base port.\n\n| Service | Port | Category |\n|---------|------|----------|\n| API | 6174 | Service |\n| Ingestion | 6175 | Service |\n| Search | 6176 | Service |\n| Tuner | 6177 | Service |\n| Observatory | 6178 | Service |\n| FalkorDB | 6179 | Database |\n| Qdrant | 6180 | Database |\n| NATS | 6181 | Database |\n| NATS Monitor | 6182 | Dev Tool |\n| PostgreSQL | 6183 | Database |\n| Optuna Dashboard | 6184 | Dev Tool |\n| Console | 6185 | Service |\n\n## Tech Stack\n\n- **TypeScript**: Bun runtime, TypeScript 7 (tsgo), Biome\n- **Python**: uv, Ruff, FastAPI, Optuna, sentence-transformers\n- **Graph**: FalkorDB (Redis-based graph DB)\n- **Vectors**: Qdrant with BGE/SPLADE embeddings\n- **Messaging**: NATS JetStream\n- **Frontend**: Next.js 16, React 19, React Flow\n- **Auth**: OAuth 2.1 with RFC 7662 token introspection\n\n## Development\n\n### Local OAuth Setup\n\nAll services require OAuth authentication in local development for production parity. See [Local OAuth Setup Guide](docs/local-oauth-setup.md) for detailed configuration.\n\n**Quick start**:\n```bash\n# Configure environment (copy template)\ncp .env.local.example .env\n\n# Start all services with OAuth\nbun run infra:up\n\n# Verify OAuth server\ncurl http://localhost:6178/api/health\n```\n\nObservatory (port 6178) acts as the OAuth authorization server. All services (search, tuner, api, memory, ingestion) authenticate via token introspection.\n\n## License\n\nAGPL-3.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frawcontext%2Fengram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frawcontext%2Fengram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frawcontext%2Fengram/lists"}