aigentry-brain

AI profile and context persistence across sessions

Persistent, cross-device memory for AI agents. Exposes 26 MCP tools so Claude Code (and any MCP-compatible client) can read and write structured memories that survive context resets, sync across machines via Git, and carry policy metadata controlling scope, retention, and access.

Quick Start

npm install -g @dmsdc-ai/aigentry-brain

That's it. Three things happen automatically:

1. ~/.aigentry/ is created with a local memory profile
2. The MCP server is registered in Claude Code, Gemini CLI, and Codex
3. Setup stays local-first by default. Cross-device sync is enabled only after explicit consent.

No prompts. No manual config. On next Claude Code session, brain_context_resume loads your memory automatically.

To enable cross-device sync after you are authenticated and have given remote consent:

gh auth login --web
aigentry-brain setup --enable-sync

To start the MCP server manually:

aigentry-brain-mcp

To open the CLI dashboard:

aigentry

Why aigentry?

Most AI memory tools treat memory as a black box. You can't audit what was stored, can't control which model reads what, and can't sync across devices without a proprietary cloud.

aigentry-brain is different:

| Feature | aigentry-brain | Mem0 | Khoj | |---|---|---|---| | Local-first storage | Yes (YAML) | No (cloud) | Yes | | Git-based sync | Yes | No | No | | MCP protocol native | Yes | No | Partial | | Policy per entry (scope/TTL/sensitivity) | Yes | No | No | | Audit trail | Yes | No | No | | Cross-LLM memory | Yes | Partial | No | | Open source | MIT | OSS core | MIT | | Self-hosted | Yes | Paid tier | Yes | | Version vectors | Yes | No | No | | Session handoff | Yes | No | No | | Zero-prompt setup | Yes | No | No |

MCP Tools (26)

Once installed, these tools are available inside Claude Code:

| Tool | Description | |---|---| | brain_append | Create or update a memory entry | | brain_query | Query entries with filters (category, tags, date, content search) | | brain_search | Hybrid lexical/semantic search across memories | | brain_erase | Soft-delete an entry by ID | | brain_context_resume | Restore context summary for AI consumption | | brain_sync_status | Get current sync state | | brain_health | System health report | | brain_compact | Run manual memory compaction | | brain_experiment_run | Run replay-based search/restore experiments | | brain_append_batch | Append multiple entries in one write | | brain_erase_batch | Delete multiple entries by ID | | brain_sync_pull | Pull remote memory state | | brain_sync_push | Push local state to remote Git repo | | brain_sync_ack | Acknowledge sync completion | | brain_peers_list | List configured peer devices | | brain_peers_register | Register a peer device | | brain_export | Export memory entries | | brain_audit_log | Read the audit trail | | brain_session_export | Export session state for handoff | | brain_session_import | Import session state from another device | | brain_deliberation_ingest | Ingest deliberation synthesis results | | brain_handoff_status | Query or update handoff execution status | | brain_experiment_learn | Record experiment results and auto-learn patterns | | brain_save_session_context | Save session context for later restoration | | brain_get_session_context | Retrieve saved session context | | brain_list_projects | List all known project IDs |

Cross-Machine Sync (CMP)

The Cross Machine Protocol (CMP) uses Git as the sync transport. Each device maintains a local clone; push/pull is triggered explicitly via MCP tools or CLI.

# First grant remote consent and configure your private profile repo
gh auth login --web
aigentry-brain setup --enable-sync

# Pull from remote
aigentry brain sync pull

# Push to remote
aigentry brain sync push

Conflict resolution: Last-Write-Wins based on ISO8601 updated timestamp. Tie-breaking by device_id lexicographic order. Version vectors track causal ordering across devices.

Session handoff allows seamless context transfer between devices via brain_session_export/brain_session_import.

peers.yaml

peers:
  - id: device-macbook
    remote_url: [email protected]:you/brain-sync.git
    branch: main
  - id: device-linux
    remote_url: [email protected]:you/brain-sync.git
    branch: main

Entry Schema

Every memory entry carries:

interface Entry {
  id: string;           // "mem_..."
  category: string;     // preference | skill | fact | decision | habit | ...
  content: string;
  source: string;       // user | auto | session | settings
  confidence: number;   // 0.0 – 1.0
  tags?: string[];
  created: string;      // ISO8601
  updated: string;      // ISO8601
  deleted?: boolean;
  policy?: {
    project_id?: string;
    scope?: 'user' | 'project' | 'team';
    allowed_models?: string[];
    retention_ttl?: string;   // "30d" | "90d" | "365d" | "forever"
    sensitivity?: 'public' | 'internal' | 'confidential' | 'restricted';
  };
  version_vector?: Record<string, number>;  // causal ordering
}

Configuration

All config via environment variables:

| Variable | Default | Description | |---|---|---| | BRAIN_REMOTE_URL | — | Remote Git URL for sync | | BRAIN_ENABLE_SYNC | false | Explicit consent gate for setup-time remote sync | | BRAIN_REMOTE_CONSENT | false | Runtime override for remote sync consent | | BRAIN_REPO_PATH | ~/.aigentry/repo | Local clone path | | BRAIN_PROJECT_ID | "default" | Default project ID for new entries | | BRAIN_DEFAULT_SCOPE | "user" | Default scope (user / project / team) | | BRAIN_PEERS_PATH | ~/.aigentry/peers.yaml | Peer device config file | | BRAIN_DEVICE_ID | auto-detected | Device identifier for sync | | BRAIN_LOG_LEVEL | "info" | Log level (debug / info / warn / error) | | BRAIN_CONFIG_PATH | ~/.aigentry/config.json | Setup config file path |

Known Limitations

• LWW conflict resolution is simple — concurrent writes from multiple devices with identical timestamps break ties by device ID, not content
• Team scope access control is not yet enforced (Phase 2)
• retention_ttl auto-expiry sweeper is not yet implemented — expired entries are filtered at read time but not physically removed

The aigentry Ecosystem

| Package | Description | npm | |---|---|---| | aigentry-brain | Persistent memory + MCP server (this repo) | @dmsdc-ai/aigentry-brain | | aigentry-deliberation | Multi-session AI debate engine with cross-LLM browser integration | @dmsdc-ai/aigentry-deliberation | | aigentry-devkit | Cross-platform installer and tooling bundle | @dmsdc-ai/aigentry-devkit | | aigentry-registry | Agent and tool registry | @dmsdc-ai/aigentry-registry | | aigentry-ssot | Single source of truth sync utilities | @dmsdc-ai/aigentry-ssot |

aigentry-deliberation

The deliberation package lets multiple AI models debate a decision before committing to it. Claude responds via MCP tool; Gemini or ChatGPT respond via CDP browser automation. Transcripts are structured with explicit agree/disagree/conditional tagging and synthesized into a report.

npx @dmsdc-ai/aigentry-deliberation install

Development

git clone https://github.com/dmsdc-ai/aigentry-brain.git
cd aigentry-brain
npm install
npm run build
npm test          # 1200+ tests across 87 files
npm run lint      # ESLint + Prettier
npm run test:coverage  # Coverage report (60% threshold)

Requirements: Node.js >= 20

Troubleshooting

Stub mode ("MCP initialize succeeded but only 3 tools visible")

From v0.2.7, the MCP server uses a staged bootstrap: the stdio transport always connects and returns a valid initialize response even if the full tool set cannot be constructed. If bootstrap fails, the server enters stub mode and exposes only three tools:

| Tool | Purpose | | --- | --- | | brain_health | Status + throttled retry of the full bootstrap. Returns {status: "degraded", stage, reason, recovery_hint}. | | brain_status_degraded | Full boot error detail: stage, message, stack trace, Node/package versions. | | brain_query_readonly | Read-only memory query that reads profile.yaml directly. Safe when ProfileManager failed to construct. |

Write tools (brain_append, brain_erase, sync, experiments, etc.) are not exposed in stub mode.

How to diagnose stub mode

1. Call brain_health. Inspect reason and stage.
2. Read the full boot error:

   cat ~/.aigentry/brain/last-boot-error.json

3. Common causes:
   • Invalid env var: BRAIN_LOG_LEVEL or BRAIN_DEFAULT_SCOPE set to an unsupported value → fix the export in your shell profile.
   • Corrupt profile: ~/.aigentry/profile.yaml cannot be parsed → back up and delete, or fix the YAML.
   • Permission denied on ~/.aigentry/: adjust permissions.
   • Missing node_modules: the postinstall skipped or failed; run npm install -g @dmsdc-ai/aigentry-brain again.
   • Corporate proxy blocking npm/github: set BRAIN_POSTINSTALL_SKIP=1 before install to bypass the network-touching postinstall step.
4. After fixing the underlying cause, call brain_health once more — the throttled retry (60 s min between attempts) confirms whether a fresh bootstrap would succeed.
5. If the retry reports ok: true, restart the MCP client (Claude Code, Gemini, Codex) so the process re-enters Stage 2 and registers all 26 tools.

Bypass postinstall in restricted environments

BRAIN_POSTINSTALL_SKIP=1 npm install -g @dmsdc-ai/aigentry-brain

Useful when gh is unavailable, github is blocked, or the machine has no interactive TTY. Brain still works in local-only mode after install — the postinstall only performs zero-prompt auto-detect of a profile repo, which is optional.

Logs

• ~/.aigentry/brain/last-boot-error.json — most recent bootstrap failure (cleared on successful boot).
• Stderr of the MCP server — always carries [aigentry-brain] STUB MODE ACTIVE — ... when stub mode is engaged.

License

MIT — see LICENSE