Memory System For Agents

Portable memory system for AI coding agents and chat tools.

This package isolates a reusable project-memory workflow so it can be copied into other repositories with minimal changes.

Goals

• Keep persistent project knowledge in docs/ai/.
• Load memory lazily through docs/ai/memory.md.
• Support multiple agent ecosystems with tool-specific entry files.
• Keep the core data model tool-agnostic.

Core Structure

• docs/ai/: persistent memory, templates, locks and documentation.
• scripts/ai/: local automation for index generation, ID creation and lock enforcement.
• .github/: GitHub Copilot / VS Code adapter.
• .claude/: Claude Code adapter.
• .cursor/: Cursor Agents adapter.
• .kilocode/: Kilo Code CLI adapter.
• .agents/: generic skills adapter for agent systems that support .agents/skills.
• AGENTS.md: generic workspace instructions for agent ecosystems that support the open AGENTS.md convention.
• CLAUDE.md: Claude-friendly workspace instructions.
• GEMINI.md: Gemini-friendly workspace instructions.

Supported Adapters

GitHub Copilot / VS Code Chat / Copilot CLI

• .github/copilot-instructions.md
• .github/prompts/*.prompt.md
• .github/agents/*.agent.md
• .github/skills/*/SKILL.md
• .github/hooks/*.json

Claude Code

• CLAUDE.md
• .claude/skills/*/SKILL.md
• .claude/commands/*.md

Generic Agents / Multi-agent CLIs

• AGENTS.md
• .agents/skills/*/SKILL.md

Gemini and Other CLIs

• GEMINI.md
• AGENTS.md
• docs/ai/README.md

Cursor Agents

• .cursor/rules/memory-system.mdc
• AGENTS.md

Kilo Code CLI

• .kilocode/rules/memory-system.md
• AGENTS.md

Auto-discovery differs by tool, so this package provides multiple entry files that point to the same docs/ai/ core instead of depending on a single vendor-specific mechanism.

Commands

npm run ai:memory:index
npm run ai:memory:new-id -- DEC
npm run ai:memory:new-id -- ARCH

NPX Installer CLI

This package now includes an installer CLI so it can be used directly with npx.

npx memory-system-for-agents

The CLI provides multi-select interaction:

• Move with arrow keys.
• Select or deselect with space bar.
• Confirm with enter.

What the installer does:

• Always installs the model-agnostic core: docs/ai/** and scripts/ai/**.
• Installs adapter-specific files for the selected agent systems.
• Merges into existing folders (for example .agents, .github, .claude) without deleting current user files.
• Never overwrites existing files in the target repository.
• Avoids duplicate operations when multiple adapters share the same file.

Current adapter mapping:

• Copilot Chat / VS Code Chat: .github/**
• Claude Code: .claude/**, CLAUDE.md
• Generic Agents: .agents/**, AGENTS.md
• Gemini CLI: GEMINI.md, AGENTS.md
• Cursor Agents: .cursor/rules/memory-system.mdc, AGENTS.md
• Kilo Code CLI: .kilocode/rules/memory-system.md, AGENTS.md

The scripts use only Node.js built-ins.

Porting To Another Repository

1. Copy the contents of this folder into the target repository root.
2. Keep docs/ai/ and scripts/ai/ together.
3. Keep only the adapter files your toolchain actually uses.
4. Update instruction files if the target repo has different security, runtime or workflow requirements.
5. Run npm run ai:memory:index once to verify local paths.

Recommended Minimal Set

If you want the leanest cross-tool install, keep:

• docs/ai/**
• scripts/ai/**
• package.json
• AGENTS.md
• CLAUDE.md
• GEMINI.md

Keep .github/** only when the target repository uses GitHub Copilot customizations.

More Details

• adapters/README.md
• docs/ai/README.md
• docs/ai/memory-system-skills.md