Skip to main content

​
Memories API

The memories API stores long-term knowledge that persists across workflow sessions.

​
Categories

CategoryPurpose
factDiscovered facts about the codebase
learningLessons learned from past executions
preferenceUser preferences and conventions
contextContextual information
skillReusable patterns or procedures

​
Scopes

ScopeVisibility
globalAll projects and sessions
projectCurrent project only
sessionCurrent session only

​
Methods

​
addFact

Store a discovered fact. 
await db.memories.addFact(
  "api-endpoint",                    // key
  "The API is at /api/v2/users",     // content
  "discovered in auth.ts"            // source
);

​
addLearning

Store a lesson learned. 
await db.memories.addLearning(
  "test-pattern",
  "Use vitest for unit tests in this project",
  "package.json analysis"
);

​
addPreference

Store a user preference. 
await db.memories.addPreference(
  "commit-style",
  "Use conventional commits with scope",
  "project"  // scope
);

​
add

Generic memory addition. 
await db.memories.add({
  category: "skill",
  key: "deploy-process",
  content: "1. Run tests\n2. Build\n3. Push to main\n4. Deploy triggers automatically",
  scope: "project",
  source: "CONTRIBUTING.md",
});

​
get

Retrieve a specific memory. 
const memory = await db.memories.get("fact", "api-endpoint");
// { id, category, key, content, source, scope, ... }

​
list

List memories by category and/or scope. 
// All facts
const facts = await db.memories.list("fact");

// Project-scoped preferences
const prefs = await db.memories.list("preference", "project");

// All memories, limited
const all = await db.memories.list(undefined, undefined, 100);
Search memories by content. 
const relevant = await db.memories.search("API endpoint", "fact", 5);
// Returns memories matching the search query

​
update

Update an existing memory. 
await db.memories.update(memoryId, {
  content: "Updated content",
});

​
delete

Remove a memory. 
await db.memories.delete(memoryId);

​
stats

Get memory statistics. 
const stats = await db.memories.stats();
// {
//   total: 42,
//   byCategory: { fact: 20, learning: 15, preference: 7 },
//   byScope: { global: 10, project: 30, session: 2 }
// }

​
Usage Patterns

​
Store Discoveries

<Claude
  onFinished={async (result) => {
    // Extract and store discoveries
    if (result.output.includes("found endpoint")) {
      await db.memories.addFact(
        "discovered-endpoint",
        result.output,
        "codebase exploration"
      );
    }
  }}
>
  Explore the API structure.
</Claude>

​
Learn from Failures

<Claude
  onError={async (error) => {
    await db.memories.addLearning(
      `error-${Date.now()}`,
      `Encountered error: ${error.message}. Solution: ...`,
      "error handler"
    );
  }}
>
  Attempt the task.
</Claude>

​
Retrieve Context

async function InformedWorkflow() {
  // Load relevant memories
  const facts = await db.memories.list("fact", "project");
  const prefs = await db.memories.list("preference", "project");

  const context = [
    "Known facts:",
    ...facts.map(f => `- ${f.content}`),
    "Preferences:",
    ...prefs.map(p => `- ${p.content}`),
  ].join("\n");

  return (
    <Claude systemPrompt={context}>
      Work with knowledge of the project.
    </Claude>
  );
}

​
Types

interface Memory {
  id: string;
  category: "fact" | "learning" | "preference" | "context" | "skill";
  key: string;
  content: string;
  source?: string;
  scope: "global" | "project" | "session";
  createdAt: Date;
  updatedAt: Date;
}

interface MemoryInput {
  category: Memory["category"];
  key: string;
  content: string;
  source?: string;
  scope?: Memory["scope"];
}

State API

Short-term state

Database

Database overview