# Memory

> Capture and retrieve durable project memory the right way -- and, when the graph backend is enabled, use temporal knowledge-graph memory. Reach for this whenever you are about to write down a lasting fact, decision, convention, or gotcha ("remember that...", "note for later", "save this"), or when you need to recall what was learned before ("what did we decide about X", "have we seen this"). It explains WHEN to use `forge remember` / `forge recall` versus a per-issue `forge issue comment`, how the two public backends work (local JSONL default, opt-in Graphiti; kernel is internal-only), and -- when Graphiti is enabled -- how to add episodes and search facts via the graphiti-memory MCP tools (add_memory, search_memory_facts, search_nodes) with group_id scoping and provenance. The local backend is always the offline floor. Not for: issue create/list/close ops (issue-basics), workflow status (status), or transient scratch notes.

- Skill: `harshanandak/memory` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add harshanandak/memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harshanandak/memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: harshanandak (https://skillmd.com/u/harshanandak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/harshanandak/memory

---


# Memory

Durable project memory for agents. This skill teaches you where a fact belongs,
which backend is active, and how to use graph memory when it is enabled.

## Applies to: Forge-managed memory

This skill describes memory managed by **Forge's own store** — `forge remember` /
`forge recall`, whose backend the Backends section (below) explains. If the repo you are working in ships
its **own** memory system (a database, an API, a "log a decision" surface, an
in-app memory service), **that** system is authoritative here and this skill does
not apply — follow the repo's own memory instructions instead. When unsure, prefer
the host repo's memory over `forge remember`; a note written to the wrong store is
a note nobody finds.

## The one rule

Persistent, project-level knowledge goes to **`forge remember`** — never to a
`MEMORY.md` file, never to a scratch note that dies with the session. Retrieve it
with **`forge recall`**. Both verbs route through one backend router; the default
is a local file store, so they always work offline with zero setup.

## When to use what

- **`forge remember "<note>"`** — a lasting fact that outlives this issue: a
  convention, a decision and its rationale, a non-obvious gotcha, an environment
  quirk, a "we tried X, it failed because Y". Add `--tag <label>` for retrieval.
- **`forge recall "<query>"`** — before assuming, check what is already known.
  Search first; do not re-derive knowledge the project already recorded. Note that
  memory relevant to your current prompt **may already be injected automatically**
  (a per-turn hook surfaces the best-matching notes; silent when nothing clears the
  relevance bar). Treat auto-surfaced memory as a head start, and still `recall`
  explicitly when you need to search for something specific it did not surface.
- **`forge issue comment <id> "<note>"`** — progress or context that belongs to
  ONE issue's lifecycle (status, a blocker, a hand-off). Issue-scoped, not global.
- **Rule of thumb:** would a future session on a *different* issue want this? →
  `remember`. Is it only meaningful inside this issue? → `issue comment`.

## Backends (config: `memory.backend` in `.forge/config.yaml`)

The router picks a backend; `remember`/`recall` behave the same from your side.
The public backends are exactly two:

- **`local`** (DEFAULT) — flat JSONL at `.forge/memory/notes.jsonl`. Instant,
  offline, no dependencies, travels with the repo in git. This is the floor and
  is always available.
- **`graphiti`** — opt-in temporal **knowledge graph** served to agents over MCP.
  Richer recall (relational, temporal, provenance-tracked) but needs a graph DB
  and an LLM. See "Graph memory" below. When selected, the CLI still writes to
  the local store as a safety floor; the graph is consumed by agents via MCP.

Check the active backend with `forge doctor` — it reports the memory backend and,
for graphiti, whether the configured MCP server path is present (read-only,
non-fatal).

## Graph memory (when `memory.backend: graphiti`)

Graphiti turns notes into a **bi-temporal knowledge graph**: you add *episodes*
(text/JSON), an LLM extracts *entities* (nodes) and *facts* (edges), and every
fact keeps two timelines — when it was true in the world and when the system
learned it. Superseded facts are **invalidated, not deleted**, so you can ask
"what is true now" or "what was true at time T", with a pointer back to the
source episode (provenance).

When enabled and the `graphiti-memory` MCP server is wired into your agent, use
its tools directly:

- **`add_memory`** — record a durable fact/decision as an episode. Pass a clear
  `name`, the content, and the project `group_id` (namespaces one project's
  memory). Ingestion is LLM-backed, so treat it as async — confirm it queued,
  don't block on it. Prefer this for facts that *evolve* (status, ownership,
  versions, preferences).
- **`search_memory_facts`** — retrieve relationships/facts (edges) for a query,
  with validity windows. Use this before assuming a fact; it returns *current*
  truth plus history.
- **`search_nodes`** — find entities (people, services, components) and their
  summaries.
- Scope every call with the project's `group_id` so memory stays per-project.
- Respect provenance: facts trace back to episodes — cite them when it matters.

If graph memory is unreachable or unconfigured, fall back to `forge remember`
(local) — never lose the note. `forge doctor` surfaces a clear error when the
graphiti backend is selected but not configured.

## Good memory hygiene

- Write **atomic** facts, not essays — one decision or gotcha per note.
- Include the **why**, not just the what (rationale ages better than commands).
- Tag consistently so recall is precise.
- Recall **before** you act on an assumption; record **after** you learn something.

## Setup pointers

- Local is the default — nothing to install.
- To opt into graph memory: set `memory.backend: graphiti` (plus a
  `memory.graphiti` block) in `.forge/config.yaml`, then run FalkorDB + the
  Graphiti MCP server. Wiring the server into each agent's MCP config is a
  follow-up step. Full how-to (graph DB, LLM/embedder, privacy/cost):
  `docs/guides/memory-backends.md`. Design rationale: `docs/work/2026-07-06-graphiti-memory/research.md`.