Skip to main content
Memory is SoulForge’s long-term store. It remembers your preferences, your project’s decisions, and the sharp edges you’ve hit before — and surfaces them automatically when they’re relevant. You don’t have to ask. Memory is per-project by default, with an opt-in global scope for cross-project preferences ("use bun not npm", "be terse").

​
What gets stored

Four kinds:
CategoryExample
pref”use bun not npm”, “be terse”
decision”switched to zustand — redux was too much boilerplate”
gotcha”JWT expiry uses container clock, drifts in prod”
context”legacy/ deletes next sprint — don’t touch”
The agent writes these proactively when you share a preference, make a choice with a reason, or hit a non-obvious bug. You can also browse and edit them yourself.

​
How recall works

Before each turn, SoulForge looks at your prompt and which files you’ve been editing, then injects up to 3 relevant memories silently. The agent sees them and adjusts. You don’t have to type /memory or remember what’s stored. If nothing’s relevant, nothing’s injected — memory earns its prompt slot every turn or it doesn’t take one.

​
Browser — /memory

Type /memory to open the browser. Five tabs:
  • All — every memory across project + global. Pin, soft-delete, or supersede per row.
  • Hidden — soft-deleted entries, restorable forever.
  • Cleanup — Quick (dupes + dead file refs) and Stale (low-signal candidates) for manual review.
  • SIM — clusters of related memories.
  • Settings — read & write scopes.
Nothing is ever truly deleted. Soft-delete only, restorable forever.

​
Scopes

Two databases:
ScopeLocationUse for
Project.soulforge/memory.dbcode-specific decisions, file-scoped gotchas
Global~/.soulforge/memory.dbcross-project preferences, your style
Read scope controls which DBs the agent sees: 
all      project + global (default)
project  only this repo
global   only your preferences
none     turn recall off

​
Pinning

Pin a memory to keep it from being surfaced in cleanup suggestions and to lift its ranking in recall. Useful for non-obvious rules you want to keep close.

​
Languages

Memory works in any script — English, CJK, Arabic, Cyrillic, mixed-script identifiers. Searches use a word index plus a character n-gram index together, so paraphrases and non-Latin queries both hit.

​
Commands

CommandDescription
/memoryOpen the browser

​
Config

{
  "memory": {
    "embeddingModel": "openai/text-embedding-3-small"
  }
}
Optional. Sets a real embedding provider for semantic recall. Default is a built-in offline embedder that works without any API calls — good enough for word-overlap paraphrases.