How ayushpani/engram works
1. The repo is a monorepo for an “agentic memory” platform, not a single app.
The main product surface is the Next.js web app, but the system also includes browser/desktop capture clients, an MCP server for agent runtimes, edge reranking workers, shared SDKs, WASM performance modules, docs, and benchmark/test tooling.
2. The core runtime flow is ingestion → deduplication → storage → consolidation → retrieval.
Memories can be created from the web app, browser extension, Raycast, or third-party agent SDKs. Before being persisted, some clients use local WASM deduplication; later, background consolidation rebuilds memory as a graph and compresses clusters into higher-density facts; retrieval then reorders candidates with an edge reranker.
3. apps/web is the main user-facing control plane.
It is a Next.js app with auth, onboarding, settings, integrations, chat, document views, and memory graph views. It also exposes server routes for onboarding flows, email generation, and OG assets, and is configured for Cloudflare deployment via Wrangler/OpenNext.
4. apps/browser-extension is a capture layer at the browser edge.
It uses WXT and is split into background, content-script, popup, and welcome entrypoints. Its content scripts are specialized per site (ChatGPT, Claude, Twitter, T3), so the extension can detect context, collect page data, deduplicate it, and push it into the memory system.
5. apps/raycast-extension is a desktop capture/search surface for macOS.
It provides quick actions for adding memories and searching memories/projects directly from Raycast, acting as another ingestion and retrieval client outside the browser and web UI.
6. apps/mcp exposes Engram over the Model Context Protocol.
This is the integration boundary for external AI tools like Claude Desktop or Cursor. The app includes auth, search/rerank logic, a small UI, and Cloudflare Worker deployment config, making Engram usable as a local/remote memory provider for MCP-capable agents.
7. apps/reranker-worker is the edge retrieval accelerator.
It is the Cloudflare Worker responsible for reranking candidate memories/documents using edge AI infrastructure. The repository also has packages/edge-reranker, which appears to hold shared reranking logic used by that worker.
8. WASM packages handle the heavy local compute pieces.
packages/client-dedup-wasm supports client-side similarity/deduplication. packages/memory-consolidator handles graph clustering/consolidation. packages/reranker-wasm and packages/wasm-math provide lower-level compute helpers, but the readme notes production reranking is done at the edge with Cloudflare AI rather than pure WASM.
9. packages/memory-graph is the interactive graph visualization subsystem.
It contains canvas rendering, hit testing, simulation, viewport, hover popovers, and graph hooks. This package is reused by the web app and also has a standalone playground app, so it is a distinct visualization boundary rather than just a component.
10. packages/tools is the agent integration layer.
It contains adapters for AI SDK, OpenAI, Vercel, Mastra, VoltAgent, and shared prompt/context/memory-client utilities. This is the part of the repo that turns Engram memory into callable tools or middleware for external agent frameworks.
11. There are first-class SDK packages for Python and TypeScript consumers.
The Python packages target specific ecosystems such as OpenAI, agent frameworks, Cartesia, and Pipecat. The TypeScript SDKs and helpers live alongside them, giving external apps a narrow integration boundary without needing the full monorepo.
12. Shared internal packages keep UI, auth, validation, and client behavior consistent.
packages/lib centralizes auth, query client, similarity, IDs, and common types. packages/ui is the design system; packages/hooks holds reusable React hooks; packages/validation defines shared schemas and API shapes. These packages reduce coupling between the apps.
13. Docs, examples, and benchmarks are treated as part of the product architecture.
apps/docs is a large MDX documentation app covering concepts, APIs, integrations, deployment, and cookbooks. packages/docs-test and packages/benchmark validate the public docs/SDK behavior and measure retrieval/reranking performance against live systems.
14. Deployment is edge-first and package publishing is automated.
The readme and workflows show Cloudflare Workers, Workers AI, Vectorize, Hyperdrive, and Durable Objects as the main infrastructure targets. GitHub Actions publish SDK/package releases and deploy the reranker worker, so the repo’s architecture includes both runtime services and a release pipeline.
Main entry points: web Web app · tools Tools SDK · reranker-worker Reranker worker · browser-extension Browser extension
Components 22
Apps
User-facing surfaces and runtime services
- Web app · Main product UI for auth, onboarding, settings, chat, documents, and memory graph views.
apps/web - Browser extension · Browser-edge ingestion surface with site-specific content scripts, popup, background, and welcome flows.
apps/browser-extension - Raycast app · Desktop quick actions for adding memories and searching memories or projects.
apps/raycast-extension - MCP server · Model Context Protocol boundary exposing Engram search and rerank to external agents.
apps/mcp - Reranker worker · Edge retrieval accelerator that reranks candidates during search.
apps/reranker-worker - Docs site · Product documentation, SDK guides, concepts, cookbooks, and deployment docs.
apps/docs - Graph playground · Standalone playground for the memory graph subsystem.
apps/memory-graph-playground
Packages
Shared libraries, SDKs, compute modules, and tooling
- Memory graph · Interactive canvas-based memory graph renderer with simulation, hit testing, viewport, and hover UI.
packages/memory-graph - Tools SDK · Adapters and shared utilities for AI SDK, OpenAI, Vercel, Mastra, and VoltAgent integrations.
packages/tools - Python agents · Python packages for agent-framework, OpenAI, Cartesia, and Pipecat integrations.
packages/agent-framework-python - AI SDK · TypeScript SDK surface for tools and agent integration.
packages/ai-sdk - Core lib · Shared auth, API client, query, similarity, ID, and utility code used across apps.
packages/lib - UI kit · Shared components, typography, and visual primitives used by the web app and related surfaces.
packages/ui - Hooks · Reusable React hooks for onboarding, storage, and interaction behavior.
packages/hooks - Validation · Shared API and schema definitions for consistent client/server shapes.
packages/validation - Dedup WASM · Client-side deduplication and similarity compute used before persistence.
packages/client-dedup-wasm - Consolidator · WASM/Rust memory consolidation worker that rebuilds and compresses memory clusters.
packages/memory-consolidator - Rerank logic · Shared reranking logic used by the edge reranker worker.
packages/edge-reranker - Reranker WASM · Lower-level WASM reranking helpers and tokenizer assets.
packages/reranker-wasm - WASM math · Low-level numerical helpers shared by WASM compute modules.
packages/wasm-math - Benchmarking · Dataset, runner, metrics, and reporting for retrieval and reranking evaluation.
packages/benchmark - Docs tests · Validation harness for public docs and SDK examples across TypeScript and Python.
packages/docs-test
Connections 22
- Browser extension → Dedup WASM: dedups · Performs local similarity filtering before sending captured memories.
- Browser extension → Web app: sends memories · Pushes captured content into the main Engram system.
- Raycast app → Web app: adds/searches · Uses Engram as a desktop capture and retrieval surface.
- MCP server → Web app: queries memory · Acts as an external agent-facing access path to the core memory system.
- MCP server → Rerank logic: reranks · Applies search reranking inside the MCP boundary.
- Reranker worker → Rerank logic: uses · Worker shares reranking logic with the package layer.
- Reranker worker → Web app: serves ranking · Accelerates retrieval for the product search flow.
- Web app → Memory graph: visualizes · Embeds the graph experience for memory exploration.
- Graph playground → Memory graph: hosts · Provides a standalone sandbox for the graph renderer.
- Web app → Tools SDK: agent tools · Uses shared agent integration utilities for chat and MCP-related features.
- Web app → Core lib: shared core · Relies on common auth, queries, IDs, and client helpers.
- Web app → UI kit: renders with · Builds the product UI from shared design system components.
- Web app → Hooks: uses hooks · Shares onboarding and interaction behavior through common hooks.
- Web app → Validation: validates APIs · Shares schemas for consistent client/server data contracts.
- Tools SDK → AI SDK: adapts · Provides Engram memory tools for the AI SDK ecosystem.
- Tools SDK → Python agents: mirrors · Aligns TypeScript and Python agent integration patterns.
- Python agents → Web app: consumes API · Python SDKs integrate against the Engram backend surface.
- Docs site → Validation: documents · Tracks API shapes and product contracts through docs.
- Docs tests → Docs site: verifies · Checks docs and examples against expected SDK behavior.
- Benchmarking → Reranker worker: measures · Benchmarks retrieval and reranking behavior against live systems.
- Consolidator → Web app: feeds retrieval · Background consolidation improves the memory structures queried by the app.
- Reranker WASM → WASM math: depends on · Shares lower-level compute helpers for WASM execution.