Project structure

Understand where MemoGrafter behavior belongs and keep provider, persistence, CLI, and Studio concerns isolated.

Repository map

memo-grafter

src/
  adapters/       Provider SDK integrations
  agents/         Session and fleet-facing agents
  core/           Runtime orchestration and shared types
  ingestion/      Segmentation, extraction, and queue-backed ingest
  maintenance/    Conflict, versioning, and decay passes
  prompts/        Provider-neutral prompt construction
  retrieval/      Recall, grafting, and graph expansion
  schema/         MemoGrafter-owned schema metadata
  store/          GraphStore boundary and PostgreSQL implementation
  studio/         Provider-independent Studio preview services
  utils/          Focused reusable domain utilities
cli/
  commands/       init, migrate, doctor, and studio commands
  doctor/         Structured Doctor results and rendering
  studio/         Local server, API, repository, and bundled frontend
  utils/          Project, configuration, and database helpers
tests/
  unit/           Isolated automated tests
  package/        Published-entrypoint and CLI smoke tests
  core/           Database-backed core scenarios
  fleet/          Database-backed multi-agent scenarios
  manual/         Provider and realistic workflow smoke tests
examples/         Runnable package-user workflows
migrations/       Historical SQL migration references

Core agents and orchestration

src/agents/ exposes session-oriented and fleet-oriented workflows. src/core/ coordinates adapters, storage, ingestion, retrieval, queues, and caching without owning provider SDK details.

Keep public agent behavior thin enough to delegate reusable work to pipelines and stores.

Keep normalized shared contracts in provider-neutral types.

Preserve session identity, lifecycle filtering, and graceful resource cleanup across orchestration changes.

Pipelines and prompts

src/ingestion/ builds graph memory, while src/retrieval/ searches and assembles it for recall or grafting. src/maintenance/ manages lifecycle annotations, and src/prompts/ keeps prompt formatting separate from orchestration.

Pipeline logic should depend on small storage and adapter contracts.

Prompt modules should format normalized data rather than import provider SDKs.

Algorithm changes should include focused unit tests and realistic database-backed coverage when needed.

Storage and schema

src/store/GraphStore.ts is the persistence boundary. src/store/postgres-pgvector/ implements it with PostgreSQL and pgvector. src/schema/ is the source of truth for MemoGrafter-owned extensions, tables, indexes, and migration metadata.

Keep application-owned tables outside MemoGrafter migrations.

Update schema metadata, migration behavior, verification, tests, and documentation together.

Do not make storage code depend on provider SDKs.

Provider adapters

src/adapters/ contains OpenAI, Anthropic, Gemini, and adapter contracts. Provider SDK imports belong in their adapter modules so package users pay only for the providers they choose.

Implement normalized LLM or embedding contracts at the adapter boundary.

Keep provider-specific request types, authentication, and errors out of core pipelines.

Add adapter unit tests and focused provider smoke tests without making provider credentials necessary for unrelated suites.

CLI boundary

cli/commands/ implements project initialization, migration, Doctor, and Studio startup. cli/utils/ owns project discovery, configuration resolution, and shared database diagnostics.

Schema generation and Doctor use the provider-independent memo-grafter/schema entry point.

Migration uses memo-grafter/store.

CLI database tooling must not evaluate the provider-bearing package root.

Studio boundary

src/studio/ contains provider-independent preview services exported through memo-grafter/studio. cli/studio/ contains the local HTTP host, API, database repository, and bundled frontend.

Session browsing, graph inspection, and table browsing must work without a provider SDK.

Prompt Preview may use a configured embedder while remaining optional.

Studio is local developer tooling, not an authenticated multi-user application.

Tests and examples

tests/unit/ is the default fast suite. Package tests protect exports and CLI workflows; core and fleet suites require PostgreSQL; manual tests cover provider calls and realistic workflows.

examples/ demonstrates package-user workflows and should use public APIs rather than internal implementation shortcuts.