Metadata-Version: 2.4
Name: vinod
Version: 0.4.10
Summary: A stateful personal agent with episodic memory for Claude Code.
Author-email: Arunabh Majumdar <arunabh.majumdar@gmail.com>
License: MIT
Keywords: agent,memory,personalization,llm,productivity
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.0
Requires-Dist: anthropic>=0.40.0

# 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

```bash
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.

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:**

```bash
vinod status
```
```
Episodic entries : 31
Last 3 entries:
  [2026-04-27T21:59] agent_vinod -- Added CLAUDE.md to vinod pip package; published 0.2.3
  [2026-04-27T21:38] agent_vinod -- Wired UserPromptSubmit hook; vinod session-start command
  [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:

```bash
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.10** — 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.

---

<img src="https://raw.githubusercontent.com/motornomad/assets/main/agent_vinod.png" width="300"/>
