Skip to content

CLAUDE.md

Latest commit

 

History

History
95 lines (70 loc) · 4.3 KB

CLAUDE.md

File metadata and controls

95 lines (70 loc) · 4.3 KB

Memory Engine

Permanent memory for AI agents. Store, search, and organize knowledge across conversations.

Documentation

All project documentation lives in docs/:

Read the relevant docs before starting work on a subsystem.

Quick Reference

  • Tech stack: Bun, TypeScript, PostgreSQL 18 (pgvector, pg_textsearch, ltree, JSONB)
  • Core schema: Single table memory per engine schema (me_<slug>) -- content, meta (JSONB), tree (ltree), temporal (tstzrange), embedding (halfvec(1536))
  • Search: Hybrid BM25 + semantic via Reciprocal Rank Fusion
  • API: JSON-RPC 2.0 over HTTP -- engine RPC (/api/v1/engine/rpc) and accounts RPC (/api/v1/accounts/rpc), plus REST auth endpoints (OAuth device flow)
  • Auth: Tree-grant RBAC with PostgreSQL RLS; OAuth (GitHub, Google) for hosted accounts
  • Embedding: Vercel AI SDK; OpenAI text-embedding-3-small (1536-dim) in production; Ollama supported for local dev
  • CLI: me binary (login, logout, whoami, org, engine, invitation, memory, mcp, user, grant, role, owner, apikey, pack)

Project Structure

packages/
  cli/          # CLI and MCP server (the `me` binary)
  client/       # TypeScript client for the engine API
  engine/       # Core engine (database operations, search, embedding)
  protocol/     # Shared types and Zod schemas (JSON-RPC methods)
  hosted/       # Hosted/multi-tenant provisioning
packs/            # Memory packs (pre-built knowledge collections)
docs/
  cli/          # CLI command reference (one file per command group)
  mcp/          # MCP tool reference (one file per tool)

Note: packages/hosted is the target package name; the current implementation is split across packages/accounts (org/member/engine management, OAuth), packages/server (HTTP server, routing, RPC handlers), packages/embedding (vector embedding providers), and packages/worker (background embedding queue processor).

Build, Lint, and Test

Always use the ./bun wrapper script (auto-installs the pinned Bun version):

# Install dependencies
./bun install

# Type checking
./bun run typecheck

# Linting and formatting (auto-fix)
./bun run lint --write

# Run unit tests
./bun test

# Run a single test file
./bun test packages/cli/mcp/install.test.ts

# Shorthand for all checks (typecheck + lint + test)
./bun run check

Important: After making code changes, always run ./bun run check.

Style Guides

TypeScript: Biome for linting and formatting. Config in biome.json.

SQL: Lowercase keywords, leading-comma table definitions, inline comments after columns, native uuid with uuidv7().

create table me.memory
( id                   uuid          not null default uuidv7()  -- PK, UUIDv7
, content              text          not null                   -- memory text
, meta                 jsonb         not null default '{}'      -- arbitrary metadata
, tree                 ltree         not null default ''        -- hierarchical path
, temporal             tstzrange                                -- optional time range
, embedding            halfvec(1536)                            -- semantic vector
);

Key Design Decisions

  • Single table: All memory types live in me.memory. Complexity comes from conventions in meta and tree, not schema proliferation.
  • Database-native: Uses PostgreSQL extensions (ltree, pgvector, JSONB GIN, tstzrange, BM25) instead of application-layer abstractions.
  • Flexibility over prescription: meta accepts any JSON, tree paths are user-defined, temporal is optional. No enforced conventions.
  • MCP compatibility: All tool parameters are required (nullable for optional). Uses z.record(z.string(), z.any()) for meta instead of z.record(z.unknown()) (which crashes the MCP SDK).