Memory & knowledge

Per-user memory

Lives at ~/.fulcrum/memory/. A top-level MEMORY.md index plus one markdown file per topic. The index is auto-injected into the system prompt at session start; entry bodies are pulled on demand via the ReadMemorytool when their description matches what you're working on. This keeps the per-turn token cost flat regardless of how many memories you accumulate.

Format

Each topic file has YAML frontmatter (name, description, type) followed by a markdown body. type is one of four values, each serving a distinct purpose:

• user — facts about who you are and how you work. Role, preferred languages, workstation quirks.
• feedback— corrections and validations from past sessions. "User wants terse responses." "Tests must use a real database, not mocks."
• project — context about ongoing work. Deadlines, who-does-what, the shape of the codebase.
• reference — pointers to where information lives in external systems. Linear project IDs, dashboard URLs, doc links.

The index

MEMORY.mdis a one-line-per-memory-file index. The render is truncated past ~8000 characters before being spliced into the system prompt, so keep entries tight — one line each, with a description that's precise enough for the model to know whether the body is worth pulling.

# Fulcrum memory index

- [user_role](user-role.md) — User is a senior dev at scx.ai
- [prefers_terse_replies](prefers-terse-replies.md) — Short answers, no preamble
- [lyre_billing_credits](lyre-billing-credits.md) — Billing credit system
- [never_make_repo_public](never-make-repo-public.md) — Never make repos public

Per-project memory

Convention, not magic. Drop a CLAUDE.md or AGENTS.md at the repo root and the agent will read it as part of orienting itself in a new codebase — same way a human onboard would skim the README first. AGENTS.md is the open-standard variant some teams prefer; CLAUDE.md is the Claude Code convention. Use either; the content shape is the same.

Unlike per-user memory, project memory is not auto-injected into the system prompt by Fulcrum. The agent picks it up on demand. The upside: it lives in version control, it applies only to that repo, and it does not bloat your global context.

What goes in

• Project-specific conventions — "always use pytest", "commit messages follow conventional commits".
• Always Do / Never Do rules that apply only inside this repo.
• Resource pointers — "for refactor work, read .fulcrum/skills/refactor.md".
• Indexing or codemap state if you're using a tool like GitNexus that wants the agent to call its tools first.

Format

Plain markdown with sections like ## Always Do, ## Never Do, ## Resources. No frontmatter required. A minimal example:

# Project conventions

## Always Do
- Run `pnpm test` before committing.
- Use server components by default; mark client components with `"use client"`.

## Never Do
- Never commit to `main` directly — always open a PR.
- Never add new dependencies without checking bundle size.

## Resources
- Architecture notes: `docs/architecture.md`
- Runbook for incidents: `docs/runbook.md`

Adding memories

Three ways, depending on whether the knowledge is per-user or per-project, and whether you want to capture it mid-conversation or hand-write it.

A. Mid-conversation — "remember X"

Just tell the agent: "remember that I prefer pytest", or "save a memory: this codebase uses Drizzle, not Prisma". The agent will call the SaveMemory tool, propose a name, description, and type, and ask for approval before writing the file. If the type is wrong (e.g. it picked project when you meant feedback), tell it to fix it — these are just markdown files.

/btw is a separate command — it forks a quick side question off the current turn and rolls history back when the answer lands. It does not save a memory by itself; if the side question produces something worth remembering, ask for it explicitly.

B. Hand-written — drop a file

Create a markdown file in ~/.fulcrum/memory/ with the frontmatter, then add a one-line pointer to MEMORY.md. The frontmatter is parsed; the body is plain markdown.

---
name: prefers terse replies
description: User wants short answers — no preamble, no trailing summaries.
type: feedback
---

The user reads diffs themselves; trailing summaries waste their attention.

**Why:** previously asked me to stop summarising what I just did.
**How to apply:** keep responses ≤ 3 sentences unless explicitly asked for detail.

Then add the pointer to ~/.fulcrum/memory/MEMORY.md:

- [prefers_terse_replies](prefers-terse-replies.md) — Short answers, no preamble

C. Per-project — write CLAUDE.md / AGENTS.md

Same shape, but lives at the repo root and goes into version control:

# This repo uses pnpm and Turborepo.

## Always Do
- Run `pnpm -w build` after touching shared packages.
- Server actions live in `src/actions/` and are typed with zod.

## Never Do
- Never run `pnpm install` at the package level — always at the workspace root.

What not to put in memory

The model can derive a lot from reading the code itself. Memory should capture knowledge that cannot be recovered from the repo. Skip:

• Code patterns and architecture. The model reads the code; it doesn't need a textual summary.
• Git history. git log is authoritative — never duplicate it into memory.
• Debug fixes. The fix is in the code; the commit message has the why.
• Anything already in CLAUDE.md or AGENTS.md. Duplicating project memory into per-user memory bloats every session.
• Ephemeral task state. Use the Plan widget or a Tasks tool — see other forms of persistence below.

Inspecting and editing

The /memory slash command prints the current ~/.fulcrum/memory/MEMORY.md contents — the same index the system prompt sees. For full bodies, just cat the topic files:

$ cat ~/.fulcrum/memory/MEMORY.md
$ cat ~/.fulcrum/memory/prefers-terse-replies.md

Editing the markdown directly is fine — there's no special encoding, no database. Inside a session the agent can use ListMemories, ReadMemory, SaveMemory, and DeleteMemory; both SaveMemory and DeleteMemory require your approval before they touch disk.

Memory vs. other persistence

Memory is one of three persistence layers. Pick by lifetime:

When memory becomes stale

A memory written today may be wrong next month. If a memory says "the auth handler is in src/auth/login.ts", grep before recommending it — the file may have moved. Treat memory as a strong prior, not as ground truth. The agent will generally verify before acting, but it's worth pruning ~/.fulcrum/memory/ every few weeks. Delete what no longer applies; correct what drifted.

Next steps

• Best practices → How to get the most out of Fulcrum once memory, skills, and sub-agents are in play.
• Prompting → Writing prompts that lean on memory instead of repeating context.
• Skills → Packaged workflows you can invoke by name — distinct from memory, but they live alongside it under ~/.fulcrum/.