# memoc

> AI agents forget everything when a session ends. memoc gives them a structured memory system so they can pick up exactly where they left off — without you repeating yourself.

Scaffolds a Markdown-based project memory into any codebase. Works with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, and Gemini CLI.

## Quick Start

```bash
npx @kevin0181/memoc init

# Upgrade memoc in this project without deleting existing memory
npx @kevin0181/memoc@latest upgrade
```

Run inside your project directory. Detects your stack automatically and generates everything agents need.

`init` also creates project-local PATH helpers so agents can keep using memoc even when the global/npm bin is not on PATH.

```bash
# PowerShell
. .\.memoc\env.ps1

# sh/bash
. ./.memoc/env.sh
```

Agents are instructed to use the project-local wrapper if PATH fails:

```bash
# Windows
.\.memoc\bin\memoc.cmd summary

# macOS / Linux
.memoc/bin/memoc summary
```

---

## Ask An Agent To Install

If you are giving this repo or npm package to an AI coding agent, use a prompt like:

```text
Install memoc in this project and run init.
Use the npm package only. Run `npx @kevin0181/memoc@latest init`
from this project's root. Do not clone the GitHub repository into this project.
If npm/npx is missing, stop and ask the user to install Node.js LTS with npm first.
After init, verify with the project-local wrapper:
Windows: .\.memoc\bin\memoc.cmd summary
macOS/Linux: .memoc/bin/memoc summary
```

Agent install checklist:

1. Run `node --version` and `npm --version`. If either fails, ask the user to install Node.js LTS with npm first.
2. Run `npx @kevin0181/memoc@latest init` from the target project root.
3. Do not clone this GitHub repository into the target project. Do not download the repo ZIP as an installer.
4. `.claude/settings.json` is intentionally generated for the Claude Code Stop hook; keep or commit it only if the project wants that hook.
5. After init, do not depend on global PATH. Use the project-local wrapper when needed:
   - Windows: `.\.memoc\bin\memoc.cmd <command>`
   - macOS/Linux: `.memoc/bin/memoc <command>`

If `node --version` or `npm --version` fails, memoc cannot be installed yet. Install Node.js LTS with npm first, then repeat the steps above.

---

## The Problem

Every new AI session starts cold. You re-explain the project, the decisions already made, what's done and what isn't. The agent rediscovers what the last one figured out.

memoc installs a memory structure that agents read at session start, update as they work, and hand off to the next session — automatically.

---

## Commands

```bash
# First-time setup — scaffold memory, detect stack, install Claude Code hook
npx @kevin0181/memoc init

# Re-scan project and refresh managed sections
npx @kevin0181/memoc update

# Shared repo activity tracking
npx @kevin0181/memoc actor
npx @kevin0181/memoc actor set neneee
npx @kevin0181/memoc work "Auth refresh fix" --from-git
npx @kevin0181/memoc activity
npx @kevin0181/memoc activity --write
npx @kevin0181/memoc doctor

# Print current status in ~10 lines
npx @kevin0181/memoc summary

# Search memory/agent docs first (token-efficient)
npx @kevin0181/memoc search "auth"
npx @kevin0181/memoc search "auth" --snippets --limit 5

# Search project source/text files only when memory is not enough
npx @kevin0181/memoc grep "GetParticles"
npx @kevin0181/memoc grep "GetParticles" --snippets --limit 5

# Create raw/source records and durable wiki topic notes
npx @kevin0181/memoc ingest path/to/source.md
npx @kevin0181/memoc ingest https://example.com/spec
npx @kevin0181/memoc note "Auth flow comparison"
npx @kevin0181/memoc lint-wiki

# Estimate token cost of current memory files
npx @kevin0181/memoc tokens

# Archive and compact an oversized startup summary
npx @kevin0181/memoc trim-summary

# Compact oversized memoc files and refresh generated indexes
npx @kevin0181/memoc compress

# Add the same protocol to another agent's entry file
npx @kevin0181/memoc add cursor
npx @kevin0181/memoc add windsurf
npx @kevin0181/memoc add copilot
npx @kevin0181/memoc add gemini
```

---

## Upgrade Existing Projects

memoc never auto-updates itself. Upgrade only when you choose to run:

```bash
npx @kevin0181/memoc@latest upgrade
```

Run it from the project root. It preserves existing project memory, including:

- `.memoc/session-summary.md`
- `.memoc/02-current-project-state.md` human-written sections
- `.memoc/03-decisions.md`
- `.memoc/04-handoff.md`
- `.memoc/06-project-rules.md`
- Legacy `.memoc/log.md` if present
- Legacy `.memoc/systems/` if present (moved to `.memoc/raw/legacy-systems/` on upgrade)
- `.memoc/wiki/`

It refreshes the managed blocks, project-local wrappers, runtime copy, PATH helpers, and memoc-owned protocol templates. User-owned memory files such as `session-summary.md`, `03-decisions.md`, `04-handoff.md`, `06-project-rules.md`, and wiki topic/source pages are preserved. Upgrade also runs the `trim-summary` compaction pass so startup memory stays small. If `memoc` is not on PATH after upgrading, keep using:

```bash
# Windows
.\.memoc\bin\memoc.cmd summary

# macOS / Linux
.memoc/bin/memoc summary
```

---

## What Gets Created

```
CLAUDE.md                                    ← Claude Code entry point (auto-loaded)
AGENTS.md                                    ← Codex entry point (auto-loaded)
llms.txt                                     ← LLM-facing project map
.claude/settings.json                        ← Claude Code Stop hook

.memoc/
  bin/memoc                                  ← project-local wrapper for PATH fallback
  env.ps1 · env.sh                           ← shell helpers that prepend .memoc/bin to PATH
  session-summary.md                         ← Only required startup read (~150 tokens)
  02-current-project-state.md               ← Status, open tasks, commands
  03-decisions.md                            ← Durable decision log
  04-handoff.md                              ← Resume context, verified/unverified
  06-project-rules.md                        ← User preferences
  activity.md                                ← Short shared activity index
  actors/                                    ← Actor profiles for shared repos
  worklog/                                   ← Per-actor work records to reduce conflicts
  raw/                                       ← Immutable source material, not a startup read
  wiki/project/                              ← Project implementation wiki
  wiki/knowledge/                            ← Source-backed knowledge wiki

skills/project-memory-maintainer/SKILL.md   ← Wiki operations guide
```

---

## How Agents Use It

Every entry file (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.) gets the same protocol injected as a managed block:

```
## Session Start
- [ ] Read `.memoc/session-summary.md`
- [ ] `.pending` exists? → review changed files → update memory if needed → delete it
- [ ] If `memoc` is not found, use the project-local wrapper.

## Before Opening More Files
- [ ] Run `memoc search "<query>"` first
- [ ] Open on demand: `02` status · `04` resume · `06` rules · `llms.txt` map
- [ ] Use `memoc grep "<query>"` only when memory is not enough.
- [ ] For durable source/wiki work, use `memoc ingest`, `memoc note`, and `memoc lint-wiki`.
- [ ] In shared repos, record meaningful work with `memoc work "<title>"`.
- [ ] Keep output small: `summary`, `search --limit`, `search --snippets`

## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
- [ ] Code/config/deps changed → `02` (version, commands list, Last synced) + `session-summary.md` (status, changed, open tasks)
- [ ] Decision made → `03-decisions.md` (what & why) + `02`
- [ ] Work incomplete or risky → `04-handoff.md` (verified commands, unverified items, next steps)
- [ ] Rule/preference set → `06-project-rules.md`
- [ ] Wiki/project-memory work → read `skills/project-memory-maintainer/SKILL.md`
- [ ] Shared repo work → prefer `memoc work "<title>" --from-git`; run `memoc activity --write` only when regenerating indexes.
- [ ] Keep `session-summary.md` replace-only; completed work belongs in actor worklogs.
```

The checklist tells agents exactly when to update, which file to update, and what to record — so nothing gets missed.

---

## Token Efficiency

Startup cost is kept minimal by design.

| What loads | Tokens |
|---|---|
| `CLAUDE.md` (managed block only) | ~280 |
| `session-summary.md` (only required read) | ~150 |
| **Total startup** | **~430** |

Everything else is on-demand. Use `memoc tokens` to see the live breakdown for your project.

`session-summary.md` is a replace-only startup snapshot, not a timeline. If it grows beyond the warning threshold, run `memoc compress` or `memoc trim-summary`; completed history belongs in `.memoc/worklog/<actor>/YYYY-MM/`, and unfinished/risky resume detail belongs in `.memoc/04-handoff.md`.

---

## Claude Code Auto-Detection

`init` installs a lightweight `Stop` hook in `.claude/settings.json`. After each Claude Code response it checks:

```bash
git status --porcelain
```

If uncommitted changes exist, it writes `.memoc/.pending` with a timestamp and the changed filenames. At the next session start, Claude reads `.pending` and decides whether to update memory — then deletes the file.

No extra setup. Add `.memoc/.pending` to `.gitignore` to keep it untracked.

---

## Multi-Agent Support

`init` creates `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex) by default. All agents follow the same 3-phase checklist protocol.

Add more agents on demand:

| Command | Creates |
|---|---|
| `add cursor` | `.cursorrules` |
| `add windsurf` | `.windsurfrules` |
| `add copilot` | `.github/copilot-instructions.md` |
| `add gemini` | `GEMINI.md` |

Running `update` refreshes managed blocks in all existing agent files.

## Shared Repos

Use `memoc work "<title>" --from-git` for meaningful work in shared repositories. It creates a new actor-scoped file under `.memoc/worklog/<actor>/YYYY-MM/`, prefills branch and changed files from git, and avoids append conflicts in shared files.

Actor detection order:

1. `MEMOC_ACTOR`
2. `.memoc/local/actor` from `memoc actor set <name>`
3. `git config user.name`
4. `git config user.email`
5. OS username

`.memoc/local/` is ignored by git so each machine can keep its own actor setting.

`activity.md`, `actors/README.md`, and `worklog/README.md` are regenerated indexes. Run `memoc activity --write` when you want to refresh them from worklog files.

`log.md` is legacy. New installs do not create it, and shared activity should live in worklog files. On upgrade, an existing `.memoc/log.md` is moved to `.memoc/raw/legacy-log.md` so old history is preserved but no longer part of the normal memory flow.

---

## Supported Stacks

Auto-detected from your project files:

Node.js · Next.js · React · Vue · Svelte · Angular · Nuxt · Astro · Express · Fastify · Hono · Electron · Tauri · TypeScript · Prisma · Drizzle · Supabase · Python · FastAPI · Django · Flask · PyTorch · Rust · Go · C++ / CMake · .NET · Java · Flutter · Unreal Engine

---

## How It Works

- **New project** — scaffolds all memory files with sensible defaults.
- **Existing project** — detects your stack and fills in real project info (name, scripts, config files).
- **Already initialized** — `init` injects the managed block without touching your existing content. `update` re-scans and refreshes project-specific sections.
- **Long-running projects** — use actor worklogs for history; run `compress` to trim startup memory, archive legacy logs, and refresh generated activity indexes.

---

## Skills Plugin (Claude Code, Codex Desktop, and Skills-Compatible Agents)

Install the memoc plugin once to get `/memoc-*` slash commands in Claude Code, Codex Desktop, and agents that read the common Skills location:

```bash
# Install memoc globally (if not already)
npm install -g @kevin0181/memoc

# Register the plugin and global skills (run once)
memoc install-plugin

# Then restart open agent apps
```

Or via npx (no global install needed):

```bash
npx @kevin0181/memoc install-plugin
```

To remove:

```bash
memoc uninstall-plugin
```

`install-plugin` writes the Claude Code plugin to `~/.claude/plugins/cache/memoc/`, enables `"memoc@memoc"` in `~/.claude/settings.json`, and installs global Skills entries under `~/.agents/skills/` for Codex Desktop and other skills-compatible agents. It is idempotent — safe to re-run after upgrading memoc.

### Available skills

| Skill | What it does |
|-------|-------------|
| `/memoc` | Follow the full memoc memory operating protocol |
| `/memoc-init` | Initialize memoc in the current project |
| `/memoc-upgrade` | Upgrade memoc, preserve memory |
| `/memoc-search` | Search memory/agent docs |
| `/memoc-work` | Create actor worklog entry |
| `/memoc-note` | Save durable topic/query-result scaffold |
| `/memoc-doctor` | Check common memoc health issues |
| `/memoc-compress` | Compact memory files, refresh indexes |
| `/memoc-code` | Apply Karpathy-inspired coding guardrails |
| `/memoc-think` | Surface assumptions, ambiguity, and tradeoffs before coding |
| `/memoc-simple` | Keep the implementation minimal and avoid overengineering |
| `/memoc-scope` | Make surgical diffs without unrelated refactors |
| `/memoc-goal` | Define success criteria and verify with tests/repros |

The `/memoc-code` family is adapted from [`multica-ai/andrej-karpathy-skills`](https://github.com/multica-ai/andrej-karpathy-skills), MIT licensed, with short memoc names for coding workflows.

---

## License

MIT