vinod 0.5.0

A stateful personal agent with episodic memory for Claude Code.

vinod

Persistent memory for Claude Code. Every session picks up where the last one left off.

No context pasting. No handoff docs. Vinod stores what you built, what you decided, and what's next — and surfaces it automatically at the start of every Claude Code session.

GitHub: motornomad/agent_vinod

---

Install

pip install vinod
vinod init

Install globally, not inside a venv. Vinod runs as a background hook every time Claude Code starts — it needs to be on your system PATH, not scoped to a project environment.

Windows: If vinod is not found after install, your Python Scripts folder may not be in PATH. Fix it in PowerShell:

$p = python -c "import sys; print(sys.prefix + '\Scripts')"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$p", "User")

Then open a new terminal and run vinod init again. Git Bash users: add export PATH="$PATH:/c/Users/<your-username>/AppData/Roaming/Python/Python3XX/Scripts" to ~/.bashrc and run source ~/.bashrc.

Restart Claude Code. That's it.

---

What happens after vinod init

vinod init does four things:

1. Scaffolds ~/.vinod/ — episodic log, beliefs file, agent identity files
2. Writes ~/.claude/CLAUDE.md — tells Claude how to use the memory
3. Registers a UserPromptSubmit hook (vinod session-start) — injects your recent memory into every new session automatically
4. Registers a Stop hook (vinod session-end) — summarises and saves the session when Claude Code closes

Both hooks are wired into ~/.claude/settings.json. Claude Code runs them for you — no manual steps.

---

How it works

Session start (automatic)

When you open Claude Code and send your first message, the vinod session-start hook fires before Claude responds. It reads your last 15 episodic entries and any active beliefs, then injects a briefing into the conversation context. Claude sees this and does two things:

1. Summarises what was last worked on in 2–3 sentences
2. Asks: "Want to continue there, or work on something else?"

You didn't paste anything. Claude already knows.

Session end (automatic)

When Claude Code stops (or you close the session), the vinod session-end hook fires. It parses the session transcript, summarises what was built or decided, and appends an episodic entry to ~/.vinod/memory/episodic.jsonl.

If you have an Anthropic API key configured (vinod config set-api-key <key>), summaries are generated by Claude Haiku with a cached system prompt. Otherwise, a rule-based summariser runs as a fallback.

---

Memory layout

~/.vinod/
├── CONTEXT.md                  # fallback: paste into any session without hook support
├── agent/
│   ├── system_prompt.md        # Claude's identity and role (edit to personalise)
│   └── guardrails.md           # hard limits (edit to add constraints)
└── memory/
    ├── episodic.jsonl          # append-only log of sessions and decisions
    ├── consolidation_state.json # last consolidation run metadata
    └── semantic/
        └── beliefs.json        # stable invariants that override episodic memory

Episodic vs semantic

Episodic memory is the rolling log. Every session writes an entry: what project, what was built, which files were touched. The last 15 entries are injected at session start.

Semantic memory (beliefs.json) is for stable facts that should always hold — architectural constraints, research invariants, hard decisions. Beliefs override episodic when they conflict. You can edit this file directly, or let vinod consolidate promote patterns automatically.

---

Consolidation: episodic → semantic

After you have a few weeks of sessions, run:

vinod consolidate

Vinod reads your recent episodic log, calls Claude Haiku, and promotes recurring patterns into beliefs.json automatically. Beliefs are deduplicated and confidence-scored.

vinod consolidate --dry-run        # preview without writing
vinod consolidate --days 60        # read 60 days instead of 30

Requires an API key (vinod config set-api-key sk-ant-...). You can also schedule this via cron — e.g., weekly.

---

MCP tools (available inside sessions)

Claude Code connects to Vinod via MCP (stdio transport, registered by vinod init):

Tool	What it does
read_memory	Returns the last N episodic entries
write_episode	Writes a richer episodic entry than the hook would produce
get_beliefs	Returns beliefs.json
search_episodes	Filters episodic entries by project name and/or tags
consolidate	Triggers episodic → semantic promotion (requires API key)
update_belief	Adjusts a belief's confidence or retires it

In practice the basic tools are called automatically by the hooks, but you can invoke any of them explicitly — e.g., say "close session" to trigger a detailed write_episode call, or "consolidate my memory" to promote today's patterns into beliefs.

---

CLI reference

vinod init [--no-mcp]              scaffold ~/.vinod/, register MCP and both hooks
vinod status                       episode count, recent entries, belief summary, consolidation state
vinod log -p <proj> -s <msg>       write a manual episodic entry
vinod consolidate [--days N]       promote episodic patterns into beliefs via Claude API
  [--dry-run]
vinod config set-api-key <key>     store an Anthropic key for LLM-based summaries and consolidation
vinod config show                  show current config
vinod uninstall                    remove ~/.vinod/, deregister hooks and MCP from settings.json
vinod mcp                          start the MCP server (Claude Code calls this; you don't need to)

---

Day-by-day experience

Day 1: pip install vinod && vinod init, restart Claude Code. First session starts cold (empty log). Work normally. At end, say "close session" — Claude writes a detailed first entry.

Day 2+: Open Claude Code, send any message. Vinod injects your memory. Claude briefs you on yesterday's work and asks what's next. You answer. No context pasting required.

After a few weeks: Run vinod consolidate. Stable patterns from your session history become beliefs that persist across all future sessions.

Checking state:

vinod status

Episodic entries : 31
Last 3 entries:
  [2026-04-27T21:59] my-project -- Added auth middleware; deployed to staging
  [2026-04-27T21:38] my-project -- Wired logging pipeline; fixed retry logic
  [2026-04-27T04:29] code-server -- Google OAuth + HTTPS proxy live
Beliefs          : 5 total, 5 active
  [92%] User works primarily on my-project and code-server in parallel
  [85%] Auth middleware is the current critical path
  [78%] Deployments go to staging first, then prod after review
Last consolidate : 2026-04-28T02:00  (+3 beliefs from 28 episodes)
MCP registered   : yes

---

Optional: LLM-based session summaries

By default, session summaries are generated by a rule-based parser (fast, no API key needed). For richer summaries and consolidation support:

vinod config set-api-key sk-ant-...

Vinod will use Claude Haiku (cached system prompt) to summarise each session and to run consolidation. Falls back to rule-based if the API call fails.

---

Status

0.5.0 — Consolidation: vinod consolidate promotes episodic patterns into semantic beliefs via Claude API. New MCP tools: search_episodes, consolidate, update_belief. Richer vinod status with belief confidence summary and last consolidation state. Fixed beliefs display bug (beliefs were silently dropped if schema used fact field instead of summary).

0.4.11 — Hook-based session start and end. vinod init registers both hooks automatically. No context pasting required. LLM summarisation with Haiku (optional). vinod config for API key management. vinod uninstall to cleanly remove. Windows fixes.

---