devmemory-ai

v3.0.0

Published

2 days ago

Agentic Memory Layer for AI-Assisted Development. Automatically documents your code changes, architecture decisions, and development intent.

DevMemory AI

Agentic Memory Layer for AI-Assisted Development
Automatically track what changed, why it changed, and the developer intent behind every commit.

DevMemory AI is an autonomous background engine that documents prompts, architecture diffs, security risks, and validation test cases for your project. It acts as a long-term memory layer for AI code assistants like Cursor, Claude, Aider, Copilot, and Gemini.

Perfect for teams that use AI-assisted development and need persistent context across sessions.

✨ Features

🤖 Multi-Agent AI Pipeline - 7 specialized agents analyze your code changes
🎯 Automatic Recording - Watches git commits and file changes automatically
🧠 Project Brain - Maintains living documentation of your codebase
📊 Build Memory - Archives every change with full context and metadata
📋 Changelog Management - Automatically generates project changelogs
🔐 Security Auditing - Flags security concerns and vulnerabilities
✅ Test Planning - Generates test cases and verification steps
🎨 Beautiful CLI - Renders markdown documentation in the terminal
🔄 Background Daemon - Runs persistently across reboots (macOS/Windows/Linux)
🆓 Free Local LLM Option - Works with Ollama (completely offline)
☁️ Cloud LLM Support - Works with OpenAI, Gemini, Claude, DeepSeek, etc.

Prerequisites

Node.js 18.0.0 or higher
Git repository (initialized with git init)
An LLM - Either local (Ollama) or cloud (OpenAI, Gemini, Claude, etc.)

Installation

[!IMPORTANT] Because DevMemory AI configures background persistence daemons (launchd plist on macOS, systemd on Linux, or startup batch files on Windows), you must install the package with administrative/superuser privileges.

macOS & Linux

Install globally via npm using sudo:

sudo npm install -g devmemory-ai

Windows

Open PowerShell or Command Prompt as Administrator and install globally:

npm install -g devmemory-ai

Verify installation:

devmemory --help

Quick Start

1. Initialize DevMemory in Your Project

cd /path/to/your/project
devmemory init

This will:

Ask you to select an AI provider (Gemini, OpenAI, Claude, Ollama, etc.)
Configure your API key (if needed)
Create .devmemory/ directory
Register a background daemon that runs automatically

2. Start Working

The daemon automatically starts and runs in the background. Simply:

Make changes to your code
Commit with git
The daemon records everything automatically

3. View Your Memory

# Show project brain (living documentation)
devmemory show brain

# Show changelog
devmemory show changelog

# Show specific build
devmemory show 1

# Show full context (paste into AI prompts)
devmemory show context

4. Stop the Daemon (Optional)

devmemory terminate

To restart it later: devmemory init

Commands Reference

| Command | Description | |---------|-------------| | devmemory init | Initialize and start background daemon | | devmemory config | Change AI provider or settings | | devmemory record -p "description" | Manually record changes | | devmemory watch | Run watcher in foreground (debugging) | | devmemory terminate | Stop and remove background daemon | | devmemory status | Display daemon status and platform commands | | devmemory logs | View recent background daemon logs | | devmemory show <target> | Display build memory, brain, changelog, or context | | devmemory context | Rebuild FULL_PROJECT_CONTEXT.md | | devmemory setup-ollama | Install and configure local Ollama | | devmemory --version | Display active package version |

Supported LLM Providers

Free/Offline (Recommended for Learning)

Ollama - Local LLM (completely free, no internet)
- Run devmemory setup-ollama to auto-install.
- If you encounter download limits or permission errors, run the official manual installer:
  - macOS & Linux: curl -fsSL https://ollama.com/install.sh | sh
  - Windows: Open PowerShell as Administrator and run irm https://ollama.com/install.ps1 | iex
- Uses qwen2.5-coder (0.5B, runs on any machine)

Cloud Providers (API Keys Required)

Google Gemini - Fast, free tier available
OpenAI - GPT-4o Mini (affordable)
Anthropic Claude - Claude 3.5 Haiku
OpenRouter - Access multiple models
DeepSeek - Cost-effective
Groq - Ultra-fast inference
Together AI - Multiple model options
Custom OpenAI-compatible endpoints

How It Works

The 7-Agent Pipeline

Summary Agent - Analyzes code changes and generates concise summaries
Architecture Agent - Creates architectural diagrams and explanations
Validation Agent - Generates test cases and verification steps
Security Agent - Audits for vulnerabilities and concerns
Regeneration Agent - Creates prompts to recreate the exact feature
Brain Agent - Updates project documentation
Changelog Agent - Maintains project changelog

Daemon Behavior

macOS: Registered with launchd, runs at login
Windows: Added to Startup folder, runs at logon
Linux: Registered as systemd user service, auto-starts

Background Recording

The daemon:

Watches file changes with configurable cooldown (default 15s)
Records git commits automatically
Runs AI analysis pipeline
Updates .devmemory/ files
Shows notifications for connection issues

Rate Limiting

To prevent runaway CPU usage, unexpected API costs, or infinite generation loops (especially when utilizing small or local models), DevMemory includes a session-based rate limit system:

Safety Break: Automatically terminates the background watcher daemon if the session API call limit is reached.
One-Time Desktop Alert: Triggers a native OS alert popup on your desktop (once per session, tracked via .devmemory/rate_limit_warned) warning you of the limit.
Reset: Resets when you run devmemory config or devmemory init.

Output Files

DevMemory creates and maintains:

.devmemory/
├── config.json                  # Your API configuration
├── project-brain.md             # Living project documentation
├── changelog.md                 # Project changelog
├── FULL_PROJECT_CONTEXT.md      # Complete context for AI prompts
├── timeline.json                # Build timeline
├── watcher_state.json           # Daemon state
└── build-001-*.md               # Individual build records
    build-002-*.md
    build-003-*.md
    ...

Example Workflow

# 1. Start a new project
mkdir my-project && cd my-project
git init

# 2. Initialize DevMemory
devmemory init
# → Select OpenAI provider → Enter API key → Done!
# → Daemon automatically starts

# 3. Make some code changes
echo "console.log('hello')" > index.js
git add index.js
git commit -m "Initial commit"

# 4. DevMemory automatically records it!
# Wait 15 seconds... daemon processes it

# 5. View what was recorded
devmemory show 1
# → Displays full analysis with architecture, risks, tests, etc.

# 6. Get context for your AI assistant
devmemory show context
# → Copy-paste into Cursor, Claude, etc.

# 7. Later, stop the daemon if needed
devmemory terminate

Configuration

DevMemory stores configuration in .devmemory/config.json:

{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "api_key": "sk-...",
  "base_url": "https://api.openai.com/v1",
  "cooldown_seconds": 15,
  "exclude_patterns": [".git", "node_modules", "*.pyc"]
}

To reconfigure: devmemory config

Troubleshooting

Checking Daemon Status

# Check daemon running state, PID, config, and OS-specific management commands:
devmemory status

Daemon not starting?

# Try restarting
devmemory terminate
devmemory init

LLM connection issues?

# For Ollama, ensure it's running:
ollama serve

# For cloud providers, verify API key:
devmemory config

Want to see logs?

# Using the CLI:
devmemory logs
# Or using tail:
tail -f .devmemory/watcher.log

Development

Clone and Install Locally

git clone https://github.com/DevMemory-ai/DevMemory.git
cd devmemory
npm install
npm run validate
node bin/index.js --help

Run Tests

npm test

File Structure

bin/index.js          # CLI entry point
src/
  agents.js           # Multi-agent pipeline
  ai.js               # LLM provider clients
  cli.js              # Command handlers
  config.js           # Configuration
  git.js              # Git integration
  ollama.js           # Ollama setup
  renderer.js         # Terminal rendering
  storage.js          # File storage
  watcher.js          # File watcher & daemon

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

MIT License - see LICENSE file for details

Support

📖 Documentation: Check the docs/ folder
🐛 Issues: https://github.com/DevMemory-ai/DevMemory/issues
💬 Discussions: https://github.com/DevMemory-ai/DevMemory/discussions

Acknowledgments

DevMemory AI empowers developers using AI assistants by maintaining persistent context and institutional memory for your codebase. Built with ❤️ for the AI-assisted development community.

Version: 3.0.0 | License: MIT | Node: >=18.0.0