@fractal-synapse/memory-workspace-plugin

Injects workspace files into the agent's context at session start. No database, no embeddings -- just raw file contents read from disk and passed to the memory injection pipeline.

The plugin looks for standard workspace instruction files (e.g. CLAUDE.md, AGENTS.md, MEMORY.md) in the agent's workspace directory and injects them as system-prompt context so the agent has persistent project-level instructions from the very first message.

Installation

npm install @fractal-synapse/memory-workspace-plugin

Quick Usage

import { MemoryInjectionPlugin } from '@fractal-synapse/memory-injection-plugin';
import { MemoryWorkspacePlugin } from '@fractal-synapse/memory-workspace-plugin';

// Create the injection coordinator and workspace plugin
const injectionPlugin = new MemoryInjectionPlugin({ logger });
const workspacePlugin = new MemoryWorkspacePlugin({ logger });

// Register the workspace plugin with the injection coordinator
injectionPlugin.register(workspacePlugin);

// Later, before the agent session starts:
workspacePlugin.setAgentWorkspace('agent-1', '/path/to/project');

Configuration

interface MemoryWorkspacePluginConfig {
  files?: (string | WorkspaceFile)[];
  logger?: LoggingInterface;
}

files

Array of files to inject at session start. Each file becomes its own ContextFragment. Accepts either a plain filename string (uses default priority 80) or a WorkspaceFile object with an explicit priority.

When omitted or empty, the default file list is used.

logger

Optional logger implementing LoggingInterface from @fractal-synapse/agent-core. Used for info/warning messages about loaded and skipped files.

WorkspaceFile Interface

interface WorkspaceFile {
  filename: string;    // filename only, resolved relative to workspacePath at runtime
  priority?: number;   // 0-100, default 80
}

• filename -- The file to look for. Resolved as path.join(workspacePath, filename) at read time.
• priority -- Determines which files survive token trimming. Higher values are kept first. Defaults to 80.

Default Files and Priorities

When no custom files config is provided, the plugin uses this list ordered into four tiers:

Tier 1 -- Cross-tool universal standards

File	Priority	Description
AGENTS.md	95	Cross-tool standard (Codex, Copilot, Windsurf, Cursor)
AGENTS.override.md	94	Codex override file, takes precedence over AGENTS.md

Tier 2 -- Tool-specific primary instruction files

File	Priority	Description
CLAUDE.md	90	Claude Code project instructions
CLAUDE.local.md	89	Claude Code local overrides (gitignored)
GEMINI.md	85	Gemini CLI project instructions
.cursorrules	80	Cursor legacy project rules
.windsurfrules	80	Windsurf legacy project rules
.augment-guidelines	80	Augment Code guidelines
.github/copilot-instructions.md	80	GitHub Copilot instructions

Tier 3 -- Agent identity and memory files

File	Priority	Description
SOUL.md	75	Agent personality, values, behavioral limits
IDENTITY.md	70	Public-facing agent metadata
USER.md	70	Human profile: name, expertise, preferences
AGENT.md	70	Agent-specific notes
MEMORY.md	65	Memory index or quick reference
TOOLS.md	60	Available tools inventory and usage notes

Tier 4 -- Supplementary files

File	Priority	Description
BOOT.md	55	Startup hook actions
CONVENTIONS.md	50	Coding conventions and style guidelines

setAgentWorkspace(agentId, path)

setAgentWorkspace(agentId: string, workspacePath: string | null): void

Registers the workspace path for a specific agent. Must be called before the session-start injection point fires. Typically called by AgentManager when creating or loading a conversation topic.

• agentId -- The agent's unique identifier.
• workspacePath -- Absolute path to the workspace directory containing the files to inject. Pass null to disable workspace injection for that agent.

How Files Are Injected

• Raw injection -- Every fragment is emitted with synthesize: false, meaning the file contents are passed to the agent exactly as-is. They are never processed through LLM synthesis.
• One fragment per file -- Each file becomes its own ContextFragment with a label like workspace:CLAUDE.md.
• Missing files skipped -- If a file does not exist, it is silently skipped with a warning log. The remaining files are still injected.
• Empty files skipped -- Files containing only whitespace are also skipped with a warning log.
• Token estimate -- Each fragment's token count is estimated as Math.ceil(content.length / 4).

Token Budget

The injection plugin allocates a default budget of 500 tokens for the session-start injection point. When the combined content of all fragments exceeds this budget, fragments are trimmed in reverse priority order -- lowest-priority files are dropped first. Higher-priority files (Tier 1) are always retained over lower-priority ones (Tier 4).

To increase the budget, configure the injection plugin with a higher value for the session-start injection point.