Capsule Memory is an open-source long-term memory service for AI agents. The monorepo packages everything you need to run the storage engine, build UIs, and consume the API from external tools. A private sibling repository (Capsule Cloud) can layer multi-tenant governance, billing, dashboards, and managed connectors on top of the OSS core.

See docs/RELEASING.md for the end-to-end playbook that turns these packages into published artefacts consumed by Capsule Cloud.

The top-level src/ directory contains the Vite UI that Modelence serves when you run the development server.

• Node.js ≥ 18.17
• pnpm (enable with corepack enable if needed)
• MongoDB or another adapter backend if you want persistence

pnpm install
cp .env.example .env     # populate MongoDB/Voyage credentials as needed
pnpm run dev             # launches Modelence server + Vite UI

Visit http://localhost:5173/memory for the operator console. The API is exposed at http://localhost:3000 with an OpenAPI document at http://localhost:3000/openapi.yaml.

To exercise the HTTP API programmatically, install the SDK after building (see below) or run the example script:

pnpm --filter examples/basic-node run dev

• pnpm run build – builds every publishable package using tsup
• pnpm run clean – removes build outputs
• pnpm run typecheck – TypeScript structural checks
• pnpm run lint – lint all workspaces (if ESLint is configured locally)

Each package exposes its own scripts if you prefer scoped builds, e.g. pnpm --filter @capsule/core run build.

The server serves /openapi.yaml directly from packages/core. Schemathesis-based CI in .github/workflows/contract.yml verifies PRs against this contract. Keep the spec up to date when you introduce new endpoints.

To regenerate TypeScript types in consumer projects:

pnpm exec openapi-typescript http://localhost:3000/openapi.yaml -o src/types.gen.ts

Capsule Memory uses Changesets and two GitHub Actions:

1. pnpm changeset – choose packages and bump versions
2. pnpm changeset version – apply version updates
3. Commit changes and push to main for a canary release (next tag on GitHub Packages)
4. Tag the commit (git tag v0.x.y && git push --tags) to publish stable versions to npm

Secrets required:

• NPM_TOKEN – npm publish access (stable job)
• Built-in GITHUB_TOKEN – used for canary publishes

Additional scripts are documented inline within tools/.

1. Use pnpm (pnpm install), not npm/yarn
2. Run pnpm run build before sending PRs
3. Update Changesets whenever you modify a published package
4. Keep formatting/strict TypeScript checks green (lint/typecheck targets)
5. Document new scripts or API surface in this README or relevant package README

import { CapsuleClient } from '@capsule/sdk-js';

const client = new CapsuleClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'demo-key',
  orgId: 'local-org',
  projectId: 'memory-lab',
  defaultSubjectId: 'agent-007'
});

await client.storeMemory({
  content: 'Remind me to send the demo deck every Monday morning.',
  pinned: true,
  tags: ['reminder', 'demo']
});

const results = await client.search({ query: 'demo deck reminder' });
console.log(results.results.map((hit) => hit.id));

See examples/basic-node for a full running sample.

The open-source roadmap lives in docs/memory-roadmap.md. Guidance for structuring a private Cloud overlay (multi-tenancy, billing, dashboards, managed connectors) is available in docs/cloud/structure.md and the cloud/ scaffold.

Licensed under the Capsule Source License v1.0. You may self-host and modify Capsule Memory for your own applications, but you may not provide it as a hosted service or sell it commercially without a Capsule agreement. See LICENSE for full details or email [email protected] for enterprise licensing.