Context Generation & Priming
Relevant source files
The following files were used as context for generating this wiki page:
Context Generation & Priming is the core mechanism by which claude-mem ensures continuity of knowledge across disparate AI development sessions. It functions by capturing tool usage observations, compressing them, and injecting semantic summaries back into the AI agent's environment. This process allows the agent to "remember" past decisions, bug fixes, and architectural choices without manual user intervention. Sources: README.md, CLAUDE.md:6-10
Within the Cursor IDE, this is achieved through a specialized rules-based injection system that auto-populates context files based on project activity. For Claude Code, it utilizes lifecycle hooks to prime the session at startup and during prompt submission. Sources: cursor-hooks/CONTEXT-INJECTION.md, src/services/worker-service.ts:315-325
Architecture and Data Flow
The context lifecycle is distributed between local IDE hooks and a centralized Worker Service. The Worker Service acts as the orchestrator, managing a SQLite database for persistent storage and a Chroma vector database for semantic retrieval. Sources: src/services/worker/README.md, CLAUDE.md:14-22
High-Level Context Lifecycle
The following diagram illustrates how data flows from a tool execution to future context injection.
Sources: CLAUDE.md:14-16, src/services/worker/README.md
Cursor IDE Integration
In the Cursor environment, context injection relies on the .cursor/rules/ directory. The system automatically creates and updates a file named claude-mem-context.mdc which Cursor natively includes in chat sessions via the alwaysApply: true frontmatter. Sources: cursor-hooks/CONTEXT-INJECTION.md:1-10, tests/cursor-context-update.test.ts:47-50
Injection Points
Context is refreshed at three critical points to ensure maximum relevance:
- Pre-Prompt: The
context-inject.shhook fetches the latest context immediately before a prompt is sent. - Post-Summary: The Worker Service automatically updates the MDC file once a session summary is saved.
- Session End: A fallback update occurs via
session-summary.shto capture any final observations.
Sources: cursor-hooks/CONTEXT-INJECTION.md:16-25, src/services/worker-service.ts:114-135
The Project Registry
The Worker Service maintains a registry at ~/.claude-mem/cursor-projects.json. This allows the worker to track which local directories require context updates even when the session was initiated from a different interface (e.g., Claude Code). Sources: src/services/worker-service.ts:101-112, cursor-hooks/CONTEXT-INJECTION.md:71-75
Worker Service API Endpoints
The Worker Service exposes several endpoints specifically for context management and priming.
| Endpoint | Method | Description |
|---|---|---|
/api/context/inject | GET | Fetches the compressed context for a specific project. |
/api/context/preview | GET | Provides a preview of the current context buffer. |
/api/search/recent-context | GET | Retrieves the most recent observations for priming. |
/api/sessions/init | POST | Initializes a session and prepares the initial context state. |
Sources: src/services/worker/README.md, src/services/worker-service.ts:400-425
MCP Priming Strategy
For detailed memory retrieval, claude-mem utilizes a Model Context Protocol (MCP) server. It employs a "3-layer workflow" to optimize token usage during context priming. Sources: src/servers/mcp-server.ts:160-175, README.md (Search Tools)
MDC Context Format
Context generated for Cursor follows the Multi-Document Context (MDC) format. This format combines YAML frontmatter for configuration with Markdown for content. Sources: tests/cursor-context-update.test.ts:98-115
---
alwaysApply: true
description: "Claude-mem context from past sessions (auto-updated)"
---
# Memory Context from Past Sessions
[Semantic summaries of past bug fixes, features, and decisions]
---
*Updated after last session.*
Sources: cursor-hooks/CONTEXT-INJECTION.md:50-65, tests/cursor-context-update.test.ts:65-75
Implementation Details
The updateCursorContextForProject function in the Worker Service is responsible for the background synchronization of memory to the IDE. Sources: src/services/worker-service.ts:114-135
export async function updateCursorContextForProject(projectName: string, port: number): Promise<void> {
const registry = readCursorRegistry();
const entry = registry[projectName];
if (!entry) return;
try {
const response = await fetch(
`http://127.0.0.1:${port}/api/context/inject?project=${encodeURIComponent(projectName)}`
);
if (!response.ok) return;
const context = await response.text();
if (!context || !context.trim()) return;
writeContextFile(entry.workspacePath, context);
} catch (error) {
logger.warn('CURSOR', 'Failed to update context file', { projectName, error: error.message });
}
}
Sources: src/services/worker-service.ts:118-135
Conclusion
Context Generation & Priming in claude-mem shifts the burden of session continuity from the user to the system. By leveraging IDE-specific rules files (Cursor) and lifecycle hooks (Claude Code), the project maintains a "living" history of the codebase. The combination of automatic background updates and a token-efficient MCP search workflow allows AI agents to operate with deep project awareness while minimizing token overhead. Sources: README.md, cursor-hooks/CONTEXT-INJECTION.md