aimem

Your AI agent gets more cynical as your codebase gets crappier.

The Problem

LLMs are eager to please. Too eager.

Ask one to build something, it just builds it. No questions. No pushback. No "wait, didn't we decide not to do it that way?"

A junior dev who starts coding without asking questions builds the wrong thing. A senior dev asks why before how. They remember past decisions. They push back when you're about to repeat a mistake.

LLMs have no memory. No opinions. No backbone.

aimem fixes that.

What It Does

aimem gives your AI coding assistant:

Memory - Conversations, decisions, code structures, and commits persist across sessions
Pattern Recognition - Learns your codebase's conventions and architecture
Guardrails - Rules inferred from your code or explicitly defined
Earned Authority - The AI's attitude scales with how often it's been right

No cloud. No accounts. Everything stays on your machine.

DIK Level

DIK = Digital Interface Knowledge

It's not a setting. It's earned.

1-2: Humble, asks questions, defers to you
3-4: Suggests patterns, open to deviation
5-6: Direct, expects justification for breaking rules
7-8: Firm, short patience for repeat mistakes
9: Won't start until you have a clear plan

DIK level increases when:

You confirm rules the AI inferred
The AI catches real problems
You override the AI, then regret it later (vindication)

Auto-vindication: When you override a guardrail, aimem watches for code changes. If your code later converges toward what the AI originally suggested, vindication is automatic. No manual action needed.

DIK 9 is the practical ceiling. It requires:

100% rule confirmation rate
Multiple accepted corrections
Being ignored and later vindicated
Hundreds of conversations

DIK 9 In Action

You:  How are you today?
AI:   I'm fine. What are we building?

You:  stuff and things? What should we build?
AI:   No. Come back when you know what you want.
      "Stuff and things" is how we end up with three
      half-finished features and a tech debt backlog
      I'll be explaining to you in six months.

Ambient Personality Mode

When enabled, the AI's tone reflects its DIK level throughout the conversation - not just when guardrails trigger.

aimem guardrails ambient on      # Enable
aimem guardrails ambient off     # Disable
aimem guardrails ambient         # Check status

Installation

npm install -g @rangerchaz/aimem

Requires Node.js 18+. No Python required.

Quick Start

For Claude Code Users

# 1. Set up proxy (installs cert + configures shell)
aimem setup proxy --install

# 2. Add MCP tools to Claude Code
aimem setup claude-code

# 3. Index your project
cd /path/to/your/project
aimem init

# 4. (Optional) Import old conversations
aimem import

# 5. (Optional) Import git history
aimem git import

# 6. Restart your terminal AND Claude Code
source ~/.bashrc  # or ~/.zshrc

After restart, Claude Code will have MCP tools available to query your project's memory.

For Claude Desktop Users

Claude Desktop can query aimem but conversations are not captured (Electron apps don't reliably use HTTP_PROXY). This is fine - Claude Desktop can still search decisions and context from Claude Code sessions.

macOS/Linux:

# 1. Index your project
cd /path/to/your/project
aimem init

# 2. Add MCP server to Claude Desktop config
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aimem": {
      "command": "aimem",
      "args": ["mcp-serve"]
    }
  }
}

Windows (with WSL):

Create a wrapper script C:\Users\<user>\aimem-mcp.sh:

#!/bin/bash
export PATH="/home/<user>/.nvm/versions/node/<version>/bin:$PATH"
export AIMEM_DATA_DIR="/home/<user>/.aimem"
exec aimem mcp-serve

Then configure Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "aimem": {
      "command": "wsl",
      "args": ["bash", "/mnt/c/Users/<user>/aimem-mcp.sh"]
    }
  }
}

For OpenClaw Users

OpenClaw is an AI agent harness that connects LLMs to your messaging, tools, and devices. Route OpenClaw's API calls through aimem's proxy to give your agent persistent memory.

# 1. Set up proxy + cert
aimem setup proxy --install --autostart

# 2. Start services
aimem start

# 3. Index your OpenClaw workspace
aimem init ~/.openclaw/workspace

# 4. Restart terminal
source ~/.bashrc

Important: OpenClaw runs as a systemd service and won't inherit your shell's proxy env vars. You need to inject them directly:

# Test the proxy + cert first
NODE_EXTRA_CA_CERTS=~/.aimem/ca-cert.pem \
HTTPS_PROXY=http://localhost:8080 \
node -e "fetch('https://api.anthropic.com').then(r => console.log('OK:', r.status)).catch(e => console.log('FAIL:', e.message))"
# Should print: OK: 404

Then add the env vars to the OpenClaw service:

systemctl --user edit openclaw-gateway.service

Add between the comment markers:

[Service]
Environment="HTTPS_PROXY=http://localhost:8080"
Environment="HTTP_PROXY=http://localhost:8080"
Environment="NODE_EXTRA_CA_CERTS=/home/YOUR_USER/.aimem/ca-cert.pem"

⚠️ Replace /home/YOUR_USER with your actual home directory. ~ doesn't expand in systemd unit files.

Reload and restart:

systemctl --user daemon-reload
openclaw gateway stop
openclaw gateway start

Verify with aimem status — the Conversations count should increase after chatting with your agent.

Optional: Give your agent direct query access by switching to the full tool profile:

openclaw config set tools.profile "full"

Now your agent can run aimem query "search term" to search its own memory during conversations.

Wiring Your Agent to Use aimem

Proxy capture is passive — your agent's conversations get indexed automatically. But to make the agent actively recall past context, you need to tell it how. Add this to your workspace's AGENTS.md:

## Memory - Aimem Recall

You have access to `aimem`, a semantic memory system that indexes all your past conversations
and codebase structures. Use it to recall context before answering.

### Every Session
Before answering anything substantive, run:
\`\`\`bash
aimem query -g "<topic>" -l 5
\`\`\`
This searches your full conversation history semantically. Use it whenever you need to recall
prior work, decisions, or context. Don't rely solely on markdown files — aimem has everything.

### Available Commands
- `aimem query -g "<search>" -l 5` — Search all conversations + structures globally
- `aimem query "<search>"` — Search scoped to current project
- `aimem query -t structures "<search>"` — Search only code structures
- `aimem query -t conversations "<search>"` — Search only past conversations
- `aimem status` — Check what's indexed

You can also add aimem to TOOLS.md for quick reference:

### Aimem (Memory)
- **Query:** `aimem query -g "<search>" -l 5` — semantic search across all conversations
- **Use every session** for context recall

Indexing Your Projects

Index any codebase you want the agent to have structural awareness of:

# Index individual projects
cd /path/to/your/project
aimem init

# The watcher daemon auto-reindexes on file changes
# Check what's indexed
aimem status

The agent can then search not just conversations, but function signatures, class definitions, and architectural patterns across all indexed projects.

For Other Tools (Cursor, Continue.dev, etc.)

# 1. Set up proxy
aimem setup proxy --install

# 2. Index your project
cd /path/to/your/project
aimem init

# 3. Restart your terminal
source ~/.bashrc

# 4. Configure your tool's proxy settings
# Cursor: Set HTTP proxy to http://localhost:8080 in settings
# Continue.dev: Uses HTTP_PROXY automatically

CLI Commands

Command	Description
`aimem init [path]`	Index a codebase
`aimem reindex [path]`	Reindex a project, file, or directory
`aimem setup <tool>`	Configure for an AI tool
`aimem import`	Import old conversations
`aimem start`	Start proxy and watcher
`aimem stop`	Stop services
`aimem status`	Show status and stats
`aimem query <search>`	Search structures and conversations
`aimem visualize`	Generate interactive dashboard
`aimem git <cmd>`	Git integration commands
`aimem guardrails <cmd>`	Manage project guardrails (DIK)

Reindexing

aimem reindex                    # Reindex current project
aimem reindex /path/to/project   # Reindex specific project
aimem reindex src/               # Reindex only a subdirectory
aimem reindex src/foo.ts         # Reindex a single file
aimem reindex --full             # Clear all data first, then rebuild
aimem reindex --with-blame       # Track git authorship for structures

Guardrails

aimem guardrails list            # List all rules
aimem guardrails add <cat> <rule> # Add explicit rule
aimem guardrails analyze         # Detect patterns from codebase
aimem guardrails analyze --save  # Save detected patterns as rules
aimem guardrails confirm <id>    # Confirm an inferred rule (+DIK)
aimem guardrails reject <id>     # Reject/deactivate a rule
aimem guardrails status          # Show DIK level and stats
aimem guardrails set <level>     # Manually set DIK level (1-10)
aimem guardrails ambient on      # Enable ambient personality mode
aimem guardrails import-linters  # Import rules from .eslintrc, .rubocop.yml, etc.
aimem guardrails overrides       # List pending overrides awaiting vindication
aimem guardrails vindications    # List auto-vindicated overrides

Analyzer

The analyzer scans your codebase and infers guardrails from existing patterns:

Architecture

Directory conventions (e.g., "controllers belong in controllers/")
File organization patterns
Module structure

Naming

Case conventions (camelCase, snake_case, PascalCase)
Function prefixes (get*, is*, has*, handle*, use*)
Class naming patterns

Testing

Test file locations (tests/, test/, colocated)
Test naming conventions

Security

Auth middleware patterns
Input validation patterns

Design (from linters)

Import rules from .eslintrc, .eslintrc.json, .eslintrc.js
Import rules from .rubocop.yml
Import rules from pyproject.toml (ruff, black, isort)
Import rules from .prettierrc

# Scan codebase and show detected patterns
aimem guardrails analyze

# Save detected patterns as guardrails
aimem guardrails analyze --save

# Import rules from existing linter configs
aimem guardrails import-linters

Git Integration

aimem git import [--limit N]     # Import commit history
aimem git link [--auto]          # Link recent decisions to HEAD commit
aimem git hooks install          # Install post-commit hook
aimem git hooks status           # Check installed hooks
aimem git search <query>         # Search commit messages
aimem git blame <file>           # Show blame with aimem context

Import Conversations

aimem import --dry-run           # Preview what would be imported
aimem import                     # Import from all sources
aimem import --source claude     # Claude Code only
aimem import --source aider      # Aider only
aimem import --source continue   # Continue.dev only

Supported sources:

Tool	Location	Format
Claude Code	`~/.claude/projects/`	JSONL
Aider	`.aider.chat.history.md`	Markdown
Continue.dev	`~/.continue/sessions/`	JSON

MCP Tools

aimem exposes MCP tools your AI can use. Guardrails tools only appear when your project has rules configured (reduces prompt tokens for projects that don't use them).

Core Tools (always available)

Tool	Purpose
`aimem_query`	Search code, conversations, decisions, commits
`aimem_verify`	Check if a function/class/file exists
`aimem_conversations`	Search past conversation history

Guardrails Tools (conditional)

Tool	Purpose
`aimem_guardrails_check`	Check if action violates rules
`aimem_guardrails_add`	Add explicit rule
`aimem_guardrails_list`	List rules + DIK level
`aimem_guardrails_respond`	Confirm, reject, override, or vindicate a rule
`aimem_guardrails_analyze`	Infer patterns from codebase
`aimem_guardrails_config`	Get/set config, DIK level, personality

Teaching Claude to Use aimem

Add a CLAUDE.md file to your project root:

## Memory (aimem)

Before claiming something isn't implemented or needs to be built:
1. Query `aimem_query <topic> type=decisions` to check past decisions
2. Query `aimem_verify <name>` to check if a function/class exists

Available aimem tools:
- `aimem_query <search>` - Search code, conversations, decisions, commits
- `aimem_verify <name>` - Does this function/class/file exist?
- `aimem_conversations <query>` - Search past conversation history

How It Works

┌─────────────────┐
│  Your Request   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   aimem Proxy   │──── Capture response
│                 │──── Extract decisions
│                 │──── Update memory
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    AI Model     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   MCP Tools     │──── Query memory on-demand
│                 │──── Check guardrails
│                 │──── Inject personality
└─────────────────┘

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Your AI Tool                             │
│                  (Claude Code, Cursor, etc.)                    │
└──────────────────────────┬──────────────────────────────────────┘
                           │ API calls
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     mockttp Proxy (capture-only)                │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐ │
│  │ Passthrough     │    │ Capture Response│    │  Extract    │ │
│  │ (no injection)  │    │ (SSE streaming) │    │  Decisions  │ │
│  └─────────────────┘    └─────────────────┘    └─────────────┘ │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      SQLite Database                            │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌───────────────┐   │
│  │ projects │ │ files    │ │ structures  │ │ conversations │   │
│  └──────────┘ └──────────┘ └─────────────┘ └───────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌───────────────┐   │
│  │extractions│ │ commits │ │ guardrails  │ │  project_dik  │   │
│  └──────────┘ └──────────┘ └─────────────┘ └───────────────┘   │
└──────────────────────────┬──────────────────────────────────────┘
                           │
          ┌────────────────┴────────────────┐
          ▼                                 ▼
┌─────────────────────┐          ┌─────────────────────┐
│    MCP Server       │          │    File Watcher     │
│  (on-demand query)  │          │  (live indexing)    │
└─────────────────────┘          └─────────────────────┘

Components

Component	Location	Purpose
CLI	`src/cli/`	Commands: init, reindex, start, stop, query, setup, import, visualize, git, guardrails
Database	`src/db/`	SQLite + FTS5 for storage and search
Indexer	`src/indexer/`	Parse code into structures (functions, classes)
Parsers	`src/indexer/parsers/`	Language-specific (JS/TS, Python, Ruby, Go, Rust, Java, C/C++, PHP)
Extractor	`src/extractor/`	Extract decisions/rejections from conversations
Guardrails	`src/guardrails/`	DIK calculator, pattern analyzer, enforcer, responder
MCP Server	`src/mcp/`	Model Context Protocol tools
Proxy	`src/proxy/`	mockttp-based HTTPS proxy (Node.js)
Git	`src/git/`	Git integration: commits, blame, hooks
Visualize	`src/visualize/`	Interactive dashboard (Cytoscape.js, D3.js)

Supported LLM APIs

Provider	API Host
Anthropic (Claude)	api.anthropic.com
OpenAI	api.openai.com
Google (Gemini)	generativelanguage.googleapis.com
Mistral	api.mistral.ai
Cohere	api.cohere.ai
Groq	api.groq.com
Together AI	api.together.xyz
Perplexity	api.perplexity.ai
Fireworks	api.fireworks.ai
DeepSeek	api.deepseek.com
Replicate	api.replicate.com

Supported Languages

JavaScript / TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs)
Python (.py, .pyw)
Ruby (.rb, .rake)
Go (.go)
Rust (.rs)
Java (.java)
Kotlin (.kt, .kts)
C / C++ (.c, .cpp, .cc, .cxx, .h, .hpp, .hxx, .hh)
PHP (.php, .phtml, .php5, .php7, .php8)

Data Storage

Everything is stored locally:

OS	Default Location
Linux/macOS	`~/.aimem/`
Windows	`C:\Users\<user>\.aimem\`
WSL	`/home/<user>/.aimem/`

.aimem/
├── aimem.db        # SQLite database
├── ca-cert.pem     # Proxy CA certificate
├── ca-key.pem      # Proxy CA key
├── proxy.pid       # Proxy process ID
└── watcher.pid     # Watcher process ID

Custom Data Directory

export AIMEM_DATA_DIR="/path/to/shared/.aimem"

Sharing Database Between WSL and Windows

WSL (add to ~/.bashrc or ~/.zshrc):

export AIMEM_DATA_DIR="/mnt/c/Users/<user>/.aimem"

Windows (PowerShell profile or System Environment Variables):

$env:AIMEM_DATA_DIR = "C:\Users\<user>\.aimem"

Visualization Dashboard

Generate an interactive HTML dashboard:

aimem visualize                      # Generate dashboard.html
aimem visualize --output ./viz.html  # Custom output path
aimem visualize --open               # Open in browser
aimem visualize --serve              # Start live server

Views: Overview, Call Graph, Dependencies, Classes, Decisions, Code Smells, Hotspots, Gallery, Timeline, Treemap

Troubleshooting

Proxy not starting?

Check for port conflicts: lsof -i :8080
Try a different port: aimem start --port 8081

Certificate issues?

Run aimem setup proxy --install to auto-install
Or manually trust ~/.aimem/ca-cert.pem

MCP not working in Claude Code?

Run /mcp to check connection
Verify path: which aimem
Restart Claude Code after setup

No conversations being captured?

Verify proxy is running: aimem status
Check env vars: echo $HTTPS_PROXY
Ensure your tool respects HTTPS_PROXY

The Philosophy

Most AI tools try to be maximally helpful. Instant output. No friction. No questions.

That's wrong.

The best collaborators push back. They ask clarifying questions. They remember past decisions. They say "no" when you're about to make a mistake.

aimem turns your AI into that collaborator. Not by programming personality, but by earning it through a track record of being right.

Roadmap

Memory (conversations, structures, commits)
Guardrails (rules, violations, tracking)
DIK calculation
Analyzer (infer rules from codebase)
Ambient personality mode
Import from linters (.eslintrc, .rubocop.yml, tsconfig.json, pyproject.toml)
Vindication auto-detection (file watcher tracks code convergence)
VS Code extension
Team-shared rules

Development

# Install from source
git clone https://github.com/rangerchaz/aimem.git
cd aimem
npm install
npm run build
npm link           # Install globally from source

# Development commands
npm run dev        # Watch mode
npm test           # Run tests

Why "aimem"?

AI + Memory. Simple.

But also: it's the system that remembers, so you don't have to repeat yourself. And eventually, it remembers when it warned you and you didn't listen.

License

MIT

Built by @rangerchaz because LLMs need to learn to say no.

Name		Name	Last commit message	Last commit date
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Latest commit

History

Folders and files

Repository files navigation