# hmem — Humanlike Memory for AI Agents

> Persistent 5-level hierarchical memory for AI agents. SQLite-backed, lazy-loaded.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bumblebiber-hmem`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Bumblebiber](https://agentstack.voostack.com/s/bumblebiber)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 1.6.7
- **License:** MIT
- **Upstream author:** [Bumblebiber](https://github.com/Bumblebiber)
- **Source:** https://github.com/Bumblebiber/its-over-9k
- **Website:** https://ko-fi.com/bumblebiber

## Install

```sh
agentstack add mcp-bumblebiber-hmem
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# its-over-9k - The AI Memory Framework

> Your AI forgets everything between sessions. **its-over-9k fixes that** — and a lot more.

One `load_project()` call. ~3000 tokens. Your agent knows everything important about a project — every past mistake, every decision, every open task — **across sessions, devices, and AI providers.** No setup per conversation. No "let me re-read the codebase." It just *remembers*.

> **AI agent?** Skip this file. Read [AGENT_SETUP.md](AGENT_SETUP.md) — written for you, not for humans.

---

## What This Is

its-over-9k is not a note-taking plugin. It's a **memory framework** for AI agents — a complete infrastructure layer for persistent, portable, token-efficient knowledge that survives session boundaries, device switches, and provider changes.

Four core guarantees:

| Pillar | What it means |
|--------|--------------|
| **Token efficiency** | 5-level lazy loading — you pay for what you read, never more |
| **Portability** | Same memory across Claude, Gemini, GPT, local models, any MCP client |
| **Efficient storage** | Hierarchical tree structure — context scales with depth, not flat append |
| **No context waste** | Auto-session capture + project briefing = zero re-read overhead |

---

## The Problem

Every AI session starts from zero. Your agent asks the same questions, makes the same mistakes, contradicts last week's decisions, and wastes 50k tokens loading context it already processed yesterday.

You've tried workarounds — CLAUDE.md files, custom prompts, manually pasting context. They don't scale. You have 10 projects. You switch between 3 devices. You use different AI tools.

## The Solution

```
You:    "Load project"
Agent:  [calls load_project("P0048") — 3000 tokens]
Agent:  "v1.2.9, TypeScript/SQLite/npm. 3 open bugs, 8 roadmap items.
         Last session: rebrand complete, rename_id bug fixed (89 changes).
         Next: O-Entry Auto-Purge. What's the focus today?"
```

That's it. 3000 tokens for a complete project briefing. The agent knows the stack, the architecture, the open bugs, the recent decisions, and exactly where you left off — even if "you" was a different AI on a different machine yesterday.

---

## How It Works

```
Level 1  ──  One-line summary          (always loaded — ~5k tokens for 300+ entries)
  Level 2  ──  Paragraph detail        (loaded on demand)
     Level 3  ──  Full context          (loaded on demand)
      Level 4  ──  Extended detail      (loaded on demand)
        Level 5  ──  Raw/verbatim data  (loaded on demand)
```

At session start, the agent loads Level 1 summaries — one line per memory. When it needs detail, it drills down. Your 300-entry memory costs 5k tokens to overview. A single project costs ~3000 tokens.

**Nothing is summarized away.** Level 1 is a compressed view, but Levels 2–5 hold the complete original text, word for word, accessible on demand.

---

## Framework Features

### Automatic Session Memory

Every conversation is recorded automatically. No "save your work" prompts. No manual checkpoints.

```
You type  →  Agent responds  →  Stop hook fires  →  Exchange saved to O-entry
                                                   →  Linked to active project
                                                   →  Haiku auto-titles the session
```

Switch projects mid-session? The O-entry switches too. Start a new session on a different device? The next agent sees every exchange from every device — **the conversation never dies**.

### Haiku Background Checkpoints

Every N exchanges (configurable, default 5), a Haiku subagent wakes up in the background. It reads the recent conversation, extracts lessons learned, errors encountered, and decisions made, then writes them to long-term memory — with full MCP tool access. Your main agent is never interrupted.

The checkpoint also writes a **handoff note** to the project: "Here's what was done, here's what's in progress, here's the next step." The next agent — on any device, any provider — picks up exactly where you left off.

### Project-Based, Not Session-Based

Sessions are meaningless. Projects are everything.

- O-entries are linked to the active project, not the session
- Checkpoint counters count project exchanges, not session messages
- `load_project` shows recent conversations with full context — across all devices

### Skills System

its-over-9k ships with a complete **skills layer** — structured behavior files that agents load on demand. Skills define *how* an agent should do something (debug, write memory, curate entries, handle a session start) — separate from memory, separate from prompts.

```bash
npx hmem update-skills    # Pull latest skills to your AI tool's skill directory
```

Skills are versioned and updated independently. Your agents get smarter without reinstalling. 21 skills ship by default:

| Skill | Triggers when… |
|-------|----------------|
| `o9k-session-start` | Every session start — loads project + surfaces pending git work, open tasks, misrouted O-entries |
| `o9k-using-hmem` | Meta-skill loaded at session start; defines mandatory memory habits |
| `o9k-read` | Reading from long-term memory (search, prefix filter, find_related, cross-project read) |
| `o9k-write` | Writing to hmem — picks prefix, tree location, tags, detects duplicates |
| `o9k-search` | User references something without an ID ("the bug we had", "letzte Woche") |
| `o9k-new-project` | Creating a P-entry — handles schema, sections, O-entry linking |
| `o9k-new-error` | Creating an E-entry with the strict 5-level scaffold |
| `o9k-activate` | Switching active project mid-session, plus fixing misrouted exchanges |
| `o9k-context` | Loading specific context when load_project output isn't enough |
| `o9k-recall` | Dispatching a Haiku sub-agent to search hmem |
| `o9k-dispatch` | Dispatching an isolated sub-agent for any search/lookup/calculation |
| `o9k-curate` | Cleaning up an .hmem file (mark obsolete, fix titles, consolidate dupes) |
| `o9k-migrate-o` | Migrating O-entries to the project-bound 5-level structure |
| `o9k-consolidate` | Merging session checkpoint summaries into one final O-entry summary |
| `o9k-wipe` | Prep for `/clear` — save high-value knowledge, update Next Steps |
| `o9k-config` | View/change memory settings, hooks, sync, checkpoints |
| `o9k-setup` | First-time install of hmem for Claude Code / Gemini CLI / OpenCode |
| `o9k-sync-setup` | Set up `hmem-sync` for cross-device sync |
| `o9k-update` | Update flow — runs `npm update -g`, syncs skills, applies migrations |
| `o9k-release` | Pre-publish checklist for its-over-9k itself |
| `o9k-subagent` | Template for sub-agents dispatched by `o9k-dispatch` |

### Company Memory

Beyond personal memory, agents can maintain a **shared company store** — a separate `company.hmem` that multiple agents and team members can read from. Personal and company memory coexist; agents query both simultaneously.

```typescript
import { openCompanyMemory } from 'its-over-9k';
const store = openCompanyMemory('/path/to/project');
```

### Embeddable SDK

its-over-9k ships as a fully documented TypeScript SDK — import `HmemStore` directly into your own agents, tools, or automation pipelines:

```typescript
import {
  HmemStore, openCompanyMemory, resolveHmemPath,
  loadHmemConfig, saveHmemConfig, DEFAULT_CONFIG, DEFAULT_PREFIXES, formatPrefixList,
  searchMemory,
} from 'its-over-9k';
import type {
  AgentRole, MemoryEntry, MemoryNode, HmemConfig,
  SearchResult, SearchOptions, SearchScope,
} from 'its-over-9k';

const store = new HmemStore('/path/to/agent.hmem');
const results = searchMemory('/path/to/project', 'auth token bug', { maxResults: 5 });
```

---

## MCP Tools

its-over-9k ships **two** MCP servers:

- **`hmem`** (daily-use, 13 tools) — read, write, search, project lifecycle.
- **`hmem-curate`** (maintenance, 11 tools) — bulk edits, schema migrations, backup/restore. Activate only when curating.

### `hmem` — daily-use server (13)

| Tool | What it does |
|------|-------------|
| `read_memory` | 5-level lazy read — by ID, prefix, search, time, or tag |
| `write_memory` | Create new entries with title, body, tags, links |
| `append_memory` | Add child nodes to existing entries |
| `update_memory` | Patch fields: title, body, tags, irrelevant, links |
| `search_memory` | FTS5 full-text search with sub-node attribution |
| `find_related` | Find contextually related entries by tag overlap |
| `load_project` | Activate a project + get full briefing + recent sessions |
| `read_project` | Read project without activating (comparison/reference) |
| `create_project` | Scaffold a new project entry with standard schema |
| `list_projects` | List all projects with status summary |
| `flush_context` | Persist current session context to long-term memory |
| `move_nodes` | Move a subtree under a different parent (also in curate server) |
| `set_active_device` | Register and switch between devices |

### `hmem-curate` — maintenance server (11)

| Tool | What it does |
|------|-------------|
| `memory_stats` | Per-prefix counts, total tokens, favorites, hashtags, stale-list |
| `memory_health` | Find broken links, orphan tags, empty entries, dangling chains |
| `export_memory` | Export the full .hmem to a portable JSON snapshot |
| `import_memory` | Import a JSON snapshot back into a .hmem (destructive) |
| `update_many` | Bulk-patch a set of entries (irrelevant, tags, body, etc.) |
| `tag_bulk` | Add/remove a tag across many entries |
| `tag_rename` | Rename a tag globally across all entries |
| `move_memory` | Move an entire entry to a new ID slot |
| `move_nodes` | Move a subtree under a different parent (also in main server) |
| `rename_id` | Rename an entry's ID; rewrites all inbound links |
| `reset_memory_cache` | Invalidate the in-memory L1 cache (after raw SQL writes) |

The daily `hmem` server is registered automatically by `hmem init`. `hmem-curate` is opt-in because its tools are destructive — register it when you need to curate:

```
npx hmem mcp-add-curate          # adds the curate server to Claude Code (user scope)
```

Then toggle it via `/mcp` only during curation sessions. For other MCP clients, see [Manual setup](#manual-setup).

---

## CLI Commands

After `npm install -g its-over-9k`, the `hmem` binary is on PATH.

### User-facing

| Command | Purpose |
|---------|---------|
| `hmem init` | Interactive installer for AI tools (Claude Code, OpenCode, Gemini CLI, Cursor, Windsurf, Cline). Flags: `--global` / `--local` / `--tools ` / `--dir ` / `--no-example` |
| `hmem update-skills` | Copy/sync bundled skill files to detected AI tools (called automatically on `npm install`) |
| `hmem mcp-add-curate` | Register the `hmem-curate` MCP server with Claude Code (opt-in; toggle via `/mcp` when curating) |
| `hmem doctor` | Detect stale or deprecated hmem MCP entries in host configs |
| `hmem stats` | Memory statistics + per-project token estimates + 🔴 4k threshold flagging |
| `hmem setup-hook` | Re-add the SessionStart hook to Claude Code settings (if removed) |
| `hmem version` | Show version |

### Hook drivers (called by AI tools, not by hand)

| Command | Wired into | What it does |
|---------|-----------|--------------|
| `hmem hook-startup` | UserPromptSubmit | First-message context injection (memory overview, project list, sync status). Periodic checkpoint reminders. Reads JSON from stdin |
| `hmem log-exchange` | Stop (sync) | Append the latest exchange to the active O-entry |
| `hmem checkpoint` | Stop (async) | Background Haiku/DeepSeek call — extracts lessons, errors, decisions; updates project handoff note |
| `hmem context-inject` | SessionStart[clear] | Inject project + rules context after `/clear` |
| `hmem deactivate` | SessionStart[clear] | Clear active project for current session |
| `hmem statusline` | statusLine | Render Claude Code statusline (device · active project · checkpoint counter). Reads JSON from stdin |

### Curation

| Command | Purpose |
|---------|---------|
| `hmem delete ` | Permanently delete an entry (curator only, never synced) |
| `hmem migrate-o-entries` | Migrate O-entries to the current project-bound schema |
| `hmem summarize-session ` | Generate a summary node for a session |

### Sync (requires `hmem-sync` installed)

| Command | Purpose |
|---------|---------|
| `hmem sync push` | Push local memory to the sync server |
| `hmem sync pull` | Pull latest memory from the sync server |
| `hmem sync status` | Show server URL · auth state · last-sync timestamp |
| `hmem sync setup [--join]` | Interactive passphrase + device setup |

### Backup / migration

| Command | Purpose |
|---------|---------|
| `hmem export-staging  ` | Export `.hmem` SQLite to a portable JSON staging file |
| `hmem import-staging  ` | Import a JSON staging file back into a `.hmem` |

`hmem serve` starts the MCP stdio server directly — your AI tool launches it automatically; you only run it by hand for debugging.

---

## Memory Categories

Default prefixes (configurable via `prefixes` in `hmem.config.json`):

| Prefix | Category | Example |
|--------|----------|---------|
| **P** | Project | `its-over-9k \| Active \| TS/SQLite/npm` |
| **L** | Lesson | `HMEM_AGENT_ID must be set in hooks — resolveHmemPath falls back to wrong DB` |
| **T** | Task | `T0033 hmem-sync SaaS monetization — recurring monthly tier design` |
| **E** | Error | `158 spurious O-entries created when Haiku MCP lacked HMEM_NO_SESSION guard` |
| **D** | Decision | `Project-based O-entries over session-based — sessions are meaningless` |
| **M** | Milestone | `v1.0.0 — package renamed to its-over-9k, npm rebrand complete` |
| **S** | Skill | `Skill: TypeScript debugging with source maps` |
| **N** | Navigator | High-level navigation entry (table of contents for a topic) |
| **H** | Human | `User Skill: TypeScript 9, Architecture 9, React 3` |
| **R** | Rule | `Max one npm publish per day — batch changes` |
| **O** | Original | Auto-recorded conversation history (every exchange, every device) |
| **I** | Infrastructure | `Strato Server \| Active \| Linux \| Ubuntu 22.04` |
| **C** | Convention | `Tag scheme: lowercase, prefer existing tags before inventing` |

Add custom prefixes (e.g. `A` for App, `F` for Function reference) by listing them under `prefixes` in `hmem.config.json` — they show up in `read_memory({ prefix: "X" })` filters automatically.

---

## Quick Start

### 1. Install

```bash
npm install -g its-over-9k
```

### 2. Run the interactive installer

```bash
npx hmem init
```

Detects your AI tools, creates the memory directory, configures MCP, and installs all hooks:

| Hook | When | What |
|------|------|------|
| `UserPromptSubmit` | Every message | First message: load memory overview. Every Nth: checkpoint reminder |
| `Stop` (sync) | Every response | Log exchange to active O-entry |
| `Stop` (async) | Every response | Haiku auto-titles untitled sessions |
| `SessionStart[clear]` | After /clear | Re-inject project context |

### 3. Verify

Restart your AI tool, then:

```
read_memory()
```

Empty response = working (first run). Error = check the [troubleshooting section](#troubleshooting).

### Manual setup

Claude Code — edit ~/.claude/.mcp.json

```json
{
  "mcpServers": {
    "hmem": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/its-over-9k/dist/mcp-server.js"],
      "env": {
        "HMEM_PROJECT_DIR": "/home/yourname/.hmem",
        "HMEM_AGENT_ID": "DEVELOPER"
      }
    }
  }
}
```

Find the paths:
```bash
echo "Node: $(which node)"
echo "Server: $(npm root -g)/its-over-9k/dist/mcp-server.js"
```

Open Code — edit ~/.config/opencode/opencode.json

```json
{
  "mcp": {
    "hmem": {
      "type": "local",
      "command": ["/absolute/path/to/node", "/absolute/path/to/its-over-9k/dist/mcp-server.js"],
      "environment": { "HMEM_PROJECT_DIR": "/home/yourname/.hmem" },
      "enabled": true
    }
  }
}
```

Cursor / Windsurf / Cline

Edit `~/.cursor/mcp.json`, `~/.codeium

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Bumblebiber](https://github.com/Bumblebiber)
- **Source:** [Bumblebiber/its-over-9k](https://github.com/Bumblebiber/its-over-9k)
- **License:** MIT
- **Homepage:** https://ko-fi.com/bumblebiber

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **1.6.7** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bumblebiber-hmem
- Seller: https://agentstack.voostack.com/s/bumblebiber
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.