Documentation
¶
Overview ¶
Package memory implements BroCode's cross-session project memory.
Every session starts cold; memory is the layer that lets a new session start warm. It persists durable facts about the project (architecture, build/test commands, decisions, gotchas) to .brocode/memory.md and makes them available three ways:
- Warm start — a capped excerpt of the memory file is injected into the system prompt at session start, so the agent already knows what past sessions learned without grep/glob.
- memory tool — the agent can recall (BM25 relevance), retain (add a fact), or list the memory during a turn.
- Auto-extract — on context compaction, the compaction summary's durable decisions are merged into memory automatically.
The file lives next to the project config (.brocode/memory.md) so it can be committed for the team or git-ignored for personal notes, matching the global/project layering used elsewhere in BroCode.
Index ¶
- type Store
- func (s *Store) CaptureGotcha(contextHint, gotcha string) error
- func (s *Store) CaptureMinerFindings(answer string, files []string) error
- func (s *Store) CaptureOutOfScopeFindings(answer string) int
- func (s *Store) CaptureSession(sessionID string, events []store.Event) error
- func (s *Store) List() string
- func (s *Store) MergeCompaction(goal string, decisions []string, state string) error
- func (s *Store) Path() string
- func (s *Store) PruneStale() int
- func (s *Store) Recall(query string, limit int) string
- func (s *Store) Retain(section, fact string) (bool, error)
- func (s *Store) Save() error
- func (s *Store) SetEmbedder(e *search.Embedder)
- func (s *Store) SetWarmStartBudget(n int)
- func (s *Store) SkillGotchas(skill string) []string
- func (s *Store) WarmStart() string
- func (s *Store) WarmStartRelevant(query string) string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store reads and writes the project memory file.
func NewStore ¶
NewStore opens (or creates on first write) the project memory file under workspaceDir/.brocode/memory.md. Returns nil if no workspace dir.
func (*Store) CaptureGotcha ¶
CaptureGotcha records a project-specific trap, gotcha, or failure pattern so the agent never repeats the same mistake in future sessions.
func (*Store) CaptureMinerFindings ¶
CaptureMinerFindings persists what a MINER turn actually examined plus the model's own synthesized summary into project memory. It parses markdown headers (## Architecture, ## Build & Test, ## Decisions, ## Gotchas) and bullet points, storing structured facts into their respective sections in memory.md.
func (*Store) CaptureOutOfScopeFindings ¶ added in v0.1.1
CaptureOutOfScopeFindings persists the "### OUT-OF-SCOPE FINDINGS" section a BUILDER turn's answer ends with (rule b13: capture off-task issues instead of chasing them mid-task) into project memory, so a follow-up task can pick them up instead of losing them to the chat history. Returns how many facts were retained (0 when the answer has no such section or nothing new).
func (*Store) CaptureSession ¶
CaptureSession extracts durable facts from a finished session's events WITHOUT calling the LLM (deterministic, non-blocking — safe to run on quit):
- the last real user prompt becomes a session goal note
- files the agent wrote/edited are recorded under a session note
This complements auto-extract-on-compaction: short sessions that never hit the compaction threshold still leave a trace in project memory.
func (*Store) MergeCompaction ¶
MergeCompaction persists durable facts from a compaction summary into the Decisions/Gotchas sections automatically (auto-extract on context loss).
func (*Store) PruneStale ¶ added in v0.1.2
PruneStale drops memory facts older than memoryEntryTTL to keep the memory file focused on the current project state. It is safe to call at session start — the cost is one file read + one BM25-free pass. Returns the number of facts pruned. Facts with embedded timestamps (ISO-8601 prefix) are evaluated by date; facts without timestamps are retained (conservative: never lose a fact we can't date).
func (*Store) Recall ¶
Recall searches memory facts by BM25 relevance to query, returning the top matches formatted for the model. Returns a friendly "no memory" note when empty.
func (*Store) Retain ¶
Retain adds a fact to a section, deduplicating near-identical entries. It returns true when a new fact was added. Sections default to "Notes".
func (*Store) SetEmbedder ¶ added in v0.1.1
SetEmbedder wires an embeddings endpoint for hybrid memory retrieval. Nil (or a later nil) disables it — retrieval gracefully degrades to BM25-only.
func (*Store) SetWarmStartBudget ¶ added in v0.1.1
SetWarmStartBudget caps the warm-start injection for the NEXT warm-start call (adaptive context budgeting: when the active turn is already close to the window limit, a 25KB memory block could itself trigger compaction). Pass n <= 0 to restore the default cap.
func (*Store) SkillGotchas ¶ added in v0.1.1
SkillGotchas returns the distilled repair lessons recorded for a skill (## Skill Notes entries prefixed "<skill>: "), oldest first. The engine uses it to decide when a skill has accumulated enough real gotchas (≥2) to warrant proposing a patch to its SKILL.md.
func (*Store) WarmStart ¶
WarmStart returns a capped excerpt of memory for system-prompt injection. Returns "" when the store is empty or nil.
func (*Store) WarmStartRelevant ¶
WarmStartRelevant returns a query-filtered dynamic slice of memory facts. When query is non-empty, it selects the top relevant facts matching the active task using BM25 relevance scoring, saving 70-90% of token overhead.
Source Files