A cofactor for agent memory

Cofactor

Compile your Markdown vault into a local concept graph. Tags, folders, links, and timestamps become catalyst-style questions your agent can search before the first conversation.

Install View repo

$ npm install -g cofactor-memory

0 runtime LLM calls

BGE-small local embeddings

CLI + MCP agent-ready

Most memory layers start empty

Cofactor starts with what you already wrote.

Your notes already have structure: repeated tags, dormant links, folders that carry projects, and timestamps that show when ideas changed. Cofactor reads those signals and gives agents a retrieval layer grounded in the shape of your archive.

#product-decisions [[Auth Rewrite]] folder:research #user-trust 2025 Q4 folder:meeting-notes

Setup

Point it at a folder.

$ cd ~/notes
$ cofactor init

Indexed: 384 documents
Entities: 42 tags, links, and folders
Catalysts: 168 generated locally
Chunks: 611 searchable passages

$ cofactor catalyze "why did auth change direction?"

matched catalyst · #architecture
"Where does session recovery keep colliding with shipping pressure?"

→ retros/platform-auth.md
→ adrs/session-boundary.md
→ interviews/user-12.md

Compile step

Search through questions, not just words.

Extract entities

Frontmatter tags, inline hashtags, wiki links, folders, and dates become signals.

Generate catalysts

Each salient entity gets thematic questions built from local terms and activity.

Precompute links

Catalysts are matched against BGE embeddings so query time can reuse stored structure.

Retrieve context

Your agent asks a question and receives excerpts, catalyst IDs, and file paths.

Local by default

Fast enough for every agent session. Private enough for real notes.

No account Install from npm and index folders on your machine.

No cloud search Search uses local BGE embeddings, sparse fallback vectors, and a generated index.

No cold start The first prompt can use the same compiled context as the hundredth.

No lock-in The index is readable JSON, and the source is TypeScript.

Bring a corpus

Use accumulated writing as the agent’s memory layer.

Engineering notes

ADRs, retros, incident reviews, and planning docs become searchable context.

Reading archives

Highlights and research notes surface recurring tastes, tensions, and questions.

Design exploration

Chosen and rejected options reveal the constraints a user keeps returning to.

Team onboarding

Apply a team’s catalysts to docs, transcripts, and unfamiliar project material.

Agents

Works from the shell, SDK, or MCP.

Cofactor is available as the cofactor-memory package. Use the CLI directly, import the TypeScript SDK, or run the included stdio MCP server for clients that speak Model Context Protocol.

cofactor agents codex . cofactor agents claude . cofactor mcp ./notes

Try it on your own vault

Give your agent the shape of your notes.

Get Cofactor