vinod 0.4.13

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.

---

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
    └── 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 edit this file directly.

---

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

In practice these are called automatically by the hooks, but you can also invoke them explicitly — e.g., say "close session" to trigger a detailed write_episode call that overrides the hook's summary.

---

CLI reference

vinod init [--no-mcp]          scaffold ~/.vinod/, register MCP and both hooks
vinod status                   episode count, last 3 entries, beliefs count, MCP state
vinod log -p <proj> -s <msg>   write a manual episodic entry
vinod config set-api-key <key> store an Anthropic key for LLM-based session summaries
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.

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 at code.thatshould.work
Beliefs          : 3
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:

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

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

---

Status

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: UTF-8 stdout encoding and absolute MCP path registration.

---