vinod 0.3.1

A stateful personal agent with episodic memory for Claude Code.

vinod

A stateful personal agent that learns how you work.

Vinod passively observes your work patterns — Claude Code sessions, file changes, decisions made — and builds an episodic + semantic memory of your behavior over time. It surfaces that memory back to Claude Code automatically via MCP, so every new session picks up exactly where the last one left off.

---

Install

pip install vinod
vinod init

That's the entire setup. vinod init scaffolds ~/.vinod/ and registers the MCP server in ~/.claude/settings.json. Restart Claude Code and it loads your memory automatically on every session start.

---

How it works

The problem it solves

Every Claude Code session starts cold. You paste a handoff doc, re-explain the project, re-establish context. For a one-off task that's fine. For a project you're working on for months, it's friction that compounds.

Vinod replaces the handoff doc with a living memory. Instead of you writing "here's what we built last time," vinod has already read your episodic log and knows.

What gets created by vinod init

~/.vinod/
├── CONTEXT.md                  # paste this into any Claude session as a fallback
├── agent/
│   ├── system_prompt.md        # Vinod's identity and role
│   └── guardrails.md           # what it will and won't do
└── memory/
    ├── episodic.jsonl          # append-only log of sessions and events
    └── semantic/
        └── beliefs.json        # stable behavioral patterns (you edit these)

The MCP server

After vinod init, Claude Code connects to Vinod via MCP (stdio transport). Three tools are exposed:

Tool	What it does
read_memory	Returns the last N episodic entries (default: 15)
write_episode	Appends one episodic entry from within a session
get_beliefs	Returns beliefs.json — your stable invariants

Claude Code can call these tools directly. In practice: at session start Claude reads memory, reconstructs context, and asks what you want to work on. At session end it writes an episodic entry summarizing what was built.

No cloud. No API key. Everything stays in ~/.vinod/.

---

User journey

Day 1

pip install vinod
vinod init
# restart Claude Code

Open a new Claude Code session. Claude now has access to read_memory and write_episode. On first use the log is empty — start working normally and close the session with "close session." Claude writes the first episodic entry.

Day 2+

Open Claude Code. Claude calls read_memory, reads the last 15 entries, and reconstructs what you were working on. You pick up where you left off without pasting anything.

Checking state

vinod status

Episodic entries : 23
Last 3 entries:
  [2026-04-27T01:06] agent_vinod -- Built real vinod pip package (0.2.0): vinod init...
  [2026-04-26T22:13] crosscommitvuln-bench -- Mined 3 new CVEs, dataset at 27 complete+sast
  [2026-04-26T19:17] crosscommitvuln-bench -- Completed full pipeline on all 20 CVEs
Beliefs          : 3
MCP registered   : yes

Writing a manual entry

vinod log -p my-project -s "decided to switch from SQLite to Postgres" \
  -d "latency under concurrent writes was unacceptable at 10k rows" \
  --event decision_made --tags decision infra

Useful for recording decisions that happen outside Claude Code — architecture calls, things you read, context that would otherwise be lost.

---

CLI reference

vinod init [--no-mcp]    scaffold ~/.vinod/, register MCP with Claude Code
vinod status             show episode count, last 3 entries, beliefs count, MCP state
vinod log                write a manual episodic entry (see --help for flags)
vinod mcp                start the stdio MCP server (Claude Code calls this automatically)

---

Memory architecture

Vinod uses a four-type memory model:

Type	Storage	Description
Episodic	episodic.jsonl	Append-only log: sessions, decisions, file changes
Semantic	beliefs.json	Stable facts and invariants you've confirmed
Procedural	future: QLoRA weights	Behavioral patterns learned from the corpus
Working	in-context only	What Claude holds during a live session

Right now episodic + semantic are live. Procedural memory (fine-tuning on your own corpus) is the Day 75+ phase of the roadmap.

---

Fallback: no MCP

If you're using Claude web or a context where MCP isn't available, paste ~/.vinod/CONTEXT.md at the start of your session. It points Claude to the episodic log and beliefs file and gives the same reconstruction instructions.

---

Research context

Vinod is the research infrastructure for a paper on personal behavioral modeling. The core hypothesis: a model of a person (learned from longitudinal behavioral data) is qualitatively different from a memory system for a conversation. Infinite context windows solve retrieval; they don't solve personalization.

If you're a developer interested in running the observer on your own machine and contributing behavioral data to the study, reach out: [e-mail].

---

Status

0.2.0 — MCP server live, episodic + semantic memory working, vinod init/status/log/mcp commands functional.

Observer pipeline (passive file watching, Google Sheets integration) and belief consolidation (episodic → semantic weekly rollup) are next.