Memory

Two independent memory systems, often confused. This page distinguishes them.

1. Core memory — manage_core_memory tool

The tool the LLM calls when you say “remember that…” or when it proactively wants to record a fact. Simple by design.

Storage: two plain JSON files.

Scope	Path	Survives
user	~/.codebuddy/user-memory.json	All workspaces, all conversations
project	<workspace>/.codebuddy/memory.json	Conversations in this workspace

Entry shape:

interface MemoryEntry {
  id: string;                                      // Random 7-char UUID
  category: "Knowledge" | "Rule" | "Experience";
  content: string;
  title: string;
  keywords: string;                                // Pipe-separated
  scope: "user" | "project";
  timestamp: number;                               // ms
}

Categories:

Category	Purpose
Knowledge	Facts, conventions, architecture decisions
Rule	Always/never coding standards
Experience	Lessons learned from past debugging or refactoring

Actions:

Action	Required	Behavior
add	content, category, title, scope	Create; random ID assigned
update	id + any changed fields	Finds the entry across both scopes; updates in place
delete	id	Removes wherever it lives
search	query?	Case-insensitive substring match on title, content, keywords. Returns all if no query.

Write safety: per-file FileMutex serializes concurrent writes. Atomic write-temp-rename to prevent corrupt JSON on crash.

Injection into the prompt: MemoryTool.getFormattedMemories() runs once at agent construction. All entries land in the system prompt from the first message onward. Not re-read per turn — restart the extension to pick up new entries added outside the agent (rare).

When the agent saves proactively: its system prompt instructs it to remember your name, role, coding preferences, project conventions, and anything explicitly flagged with “remember this.”

No ranking, no vector search, no MMR. Core memory is deliberately simple — a JSON store the LLM reads whole. Fancy retrieval lives in system 2 below.

2. Workspace-content search — search_vector_db tool

Separate system. Indexes your code, not your memories.

• HNSW vector index via hnsw-index.ts — semantic search over file chunks.
• BM25 keyword index (SQLite FTS4) — exact-term matching.
• Score fusion — weighted merge: 0.7 × vector + 0.3 × BM25.
• Temporal decay — recent code weighted higher (temporal-decay.ts).
• MMR re-ranking — mmr.ts — reduces redundant results.
• Reranker — reranker.ts — final quality pass.

Storage: SQLite at <workspace>/.codebuddy/vector_store.db. Populated by AstIndexingService walking the workspace on activation.

The agent calls this via search_vector_db when it needs “find code semantically similar to X.” Not the same as manage_core_memory — you can’t save_memory into the vector store, and the LLM’s remembered facts don’t go there.

Session cache

There’s also an in-process key/value cache (src/memory/base.ts) with a 30-min TTL, used for chat-history snapshots and other per-session state. Not user-facing — mentioned here so nobody reading the source is confused when they see three things called “memory.”

Files at a glance

File	What
src/tools/memory.ts	manage_core_memory tool — the JSON store
src/memory/base.ts	In-process session cache (30-min TTL)
src/memory/hybrid-search.service.ts	Workspace-content search orchestrator
src/memory/hnsw-index.ts	Vector index
src/memory/mmr.ts	MMR diversity re-ranking
src/memory/reranker.ts	Post-fusion quality pass
src/memory/temporal-decay.ts	Recency bias for workspace search
src/memory/chat-history-cache.ts	Chat-history persistence

Related

• Architecture — where memory injection sits in the middleware stack
• Semantic search — workspace vector search as a feature
• Chat history — conversation persistence