StateCore: Instructions file for Claude Code

StateCore — Claude Context

What this is

StateCore is an AI memory management system. It stores memory events, runs digest workers to build stable state, and serves a REST API for ingestion and recall.

It is the Layer 1 engine of the StateCore-App stack (see ../CLAUDE.md): open-source (MIT), self-hostable, and fronted by ../statecore-cloud (managed gateway) which ../assistant-backend uses as its memory store. Tech: pnpm + Turbo monorepo (apps/*, packages/*), TypeScript, Node ≥20 (apps/mcp: ≥22.13, it uses node:sqlite), NestJS, Prisma/Postgres+pgvector, BullMQ/Redis, Zod, Vitest, Changesets.

Commands

pnpm install
pnpm dev:api          # API only (port 3002)
pnpm dev:worker       # background workers (digest, working memory, reminders)
pnpm dev:lite         # = dev:api
pnpm test:core        # Vitest suite for @statecore/core
pnpm lint             # tsc --noEmit across apps + packages
pnpm build            # build all apps + packages
pnpm changeset        # add a changeset (releases via Changesets)
pnpm benchmark        # synthetic memory-quality benchmark suite

changeset version needs a token for its changelog generator: GITHUB_TOKEN="$(gh auth token)" pnpm exec changeset version. Releases are manual — version, commit, tag with apps/api's version, gh release create. Every package is private: true except apps/mcp (statecore-mcp), the one package that publishes to npm — see apps/mcp/README.md.

Module resolution — read before touching package.json or tsconfig

The four library packages point main at dist/index.js and types at src/index.ts. That split is deliberate and load-bearing:

• main → dist because node dist/main.js cannot load a .ts entry. The Dockerfile used to rewrite these four package.json files at image build time, which meant the image was the only place a built app could start.
• types → src so type-checking and building need no prior build. Do not "fix" this with tsconfig paths — mapping these names to real paths puts the files under the importing package's rootDir and fails every build with TS6059. Resolution through the node_modules symlink is exempt from that check.
• Vitest reads main, so vitest.shared.ts aliases the names back to source. A package that runs tests needs a vitest.config.ts importing it, or its suite silently runs against stale dist.
• tsx reads main too, so pnpm dev:* and the tsx-run scripts pass --tsconfig ../../tsconfig.dev.json, which carries the paths tsc cannot.