Skip to content

Commit 805e983

Browse files
Olow304Olow304
committed
clean up readme
1 parent e933fec commit 805e983

4 files changed

Lines changed: 134 additions & 50 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
{
1010
"name": "memvid-mind",
1111
"description": "Give Claude Code photographic memory in ONE portable file",
12-
"version": "1.0.5",
12+
"version": "1.0.6",
1313
"source": {
1414
"source": "github",
1515
"repo": "memvid/memvid-mind"

‎.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "memvid-mind",
33
"description": "Give Claude Code photographic memory in ONE portable file. Share, version, and transfer your Claude's brain.",
4-
"version": "1.0.5",
4+
"version": "1.0.6",
55
"author": {
66
"name": "Memvid",
77
"url": "https://memvid.com"

‎README.md‎

Lines changed: 131 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,20 @@
22

33
# 🧠 memvid-mind
44

5-
**Give Claude Code a memory. One file. That's it.**
5+
### **Claude Code finally remembers.**
6+
7+
*One file. Instant recall. Zero config.*
68

79
[![npm version](https://img.shields.io/npm/v/memvid-mind.svg)](https://www.npmjs.com/package/memvid-mind)
10+
[![GitHub stars](https://img.shields.io/github/stars/memvid/memvid-mind?style=social)](https://github.com/memvid/memvid-mind)
811
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
912

10-
[Installation](#installation) • [How it Works](#how-it-works) • [Commands](#commands) • [FAQ](#faq)
13+
[Installation](#-installation) • [How it Works](#-how-it-works) • [Commands](#-commands) • [FAQ](#-faq)
14+
15+
<!--
16+
TODO: Add demo GIF here
17+
![Demo](demo.gif)
18+
-->
1119

1220
</div>
1321

@@ -25,68 +33,89 @@ You: "We literally spent 3 hours on this yesterday"
2533
Claude: "I'd be happy to help you debug it from scratch!"
2634
```
2735

28-
200K context window. Zero memory between sessions.
36+
**200K context window. Zero memory between sessions.**
37+
38+
You're paying $200/month for a goldfish with a PhD.
39+
40+
---
41+
42+
## The Solution
43+
44+
```
45+
You: "What did we decide about the auth system?"
46+
47+
Claude: "Last week we chose JWT over sessions because of your
48+
microservices architecture. I also remember we had issues with
49+
the refresh token rotation - here's what we fixed..."
50+
```
2951

30-
**You're paying for a goldfish with a PhD.**
52+
**One plugin. One file. Claude remembers everything.**
3153

3254
---
3355

34-
## Installation
56+
## 🚀 Installation
57+
58+
**30 seconds. No config.**
3559

36-
**Step 1:** One-time setup (if you haven't used GitHub plugins before)
3760
```bash
61+
# One-time setup (if you haven't used GitHub plugins before)
3862
git config --global url."https://github.com/".insteadOf "git@github.com:"
3963
```
4064

41-
**Step 2:** Add marketplace and install
65+
Then in Claude Code:
4266
```
4367
/plugin marketplace add memvid/memvid-mind
4468
/plugin install memvid-mind
4569
```
4670

47-
**Step 3:** Restart Claude Code. Done!
71+
Restart Claude Code. **Done.**
4872

4973
---
5074

51-
## How it Works
75+
## 🔮 How it Works
5276

53-
After install, Claude remembers everything in **one file**:
77+
After install, Claude stores memories in **one portable file**:
5478

5579
```
5680
your-project/
5781
└── .claude/
5882
└── mind.mv2 # Claude's brain. That's it.
5983
```
6084

61-
Next session:
85+
### What Gets Captured
6286

63-
```
64-
You: "What did we decide about the auth system?"
87+
| When | What |
88+
|------|------|
89+
| **Session start** | Injects relevant context from past sessions |
90+
| **While working** | Decisions, bugs found, solutions, file changes |
91+
| **Session end** | Session summary for future recall |
6592

66-
Claude: "Last week we chose JWT over sessions because..."
67-
```
93+
### Why One File?
6894

69-
### What Gets Captured
95+
| Action | Result |
96+
|--------|--------|
97+
| `git commit` | Version control Claude's memory |
98+
| `scp file user@server:` | Transfer to any machine |
99+
| Send to teammate | Instant project onboarding |
70100

71-
| Event | What's Saved |
72-
|-------|--------------|
73-
| **Session start** | Loads relevant context from past sessions |
74-
| **While working** | File structures, decisions, bugs found, solutions |
75-
| **Session end** | Summary of what happened |
101+
**No database. No background service. No API keys. No cloud.**
76102

77-
### Why One File?
103+
---
78104

79-
- **`git commit`** - version control Claude's memory
80-
- **`scp`** - copy to another machine, it just works
81-
- **Share** - instant context transfer to teammates
105+
## 📦 Commands
82106

83-
No database. No background service. No config.
107+
```bash
108+
/mind stats # memory statistics
109+
/mind search "authentication" # find past context
110+
/mind ask "why did we choose X?" # ask your memory
111+
/mind recent # what happened lately
112+
```
84113

85114
---
86115

87-
## Endless Mode
116+
## ⚡ Endless Mode
88117

89-
Claude hits context limits fast. This compresses tool outputs ~20x:
118+
Claude hits context limits fast. memvid-mind compresses tool outputs ~20x:
90119

91120
```
92121
Before: Read (8K) + Edit (4K) + Bash (12K) = 24K tokens gone
@@ -95,36 +124,77 @@ After: Read (400) + Edit (200) + Bash (600) = 1.2K tokens
95124

96125
Keeps errors, structure, key functions. Drops the noise.
97126

127+
Work longer without hitting limits.
128+
98129
---
99130

100-
## Commands
131+
## ❓ FAQ
132+
133+
<details>
134+
<summary><b>Why is the .mv2 file ~4MB even when empty?</b></summary>
135+
136+
The `.mv2` format is designed for **instant operations** on files of any size. It pre-allocates:
137+
138+
- **Vector index** for semantic search (find memories by meaning, not just keywords)
139+
- **Write-ahead log (WAL)** for crash-safe writes
140+
- **Block-aligned storage** for O(1) random access
141+
142+
This is the same architecture used by SQLite, LevelDB, and other production databases. The 4MB overhead enables sub-millisecond operations whether you have 10 memories or 10 million.
143+
144+
*Think of it like an empty filing cabinet - it takes up space, but it's ready to organize thousands of documents instantly.*
145+
146+
</details>
147+
148+
<details>
149+
<summary><b>How big does the file get?</b></summary>
150+
151+
~1KB per memory. 1000 memories ≈ 1MB additional. The base 4MB is fixed overhead.
152+
153+
</details>
154+
155+
<details>
156+
<summary><b>Is my data private?</b></summary>
157+
158+
**100% local.** Nothing leaves your machine. No telemetry. No cloud sync. You own your data.
159+
160+
The `.mv2` file is just a file - encrypt it, back it up, delete it, share it. Your choice.
161+
162+
</details>
163+
164+
<details>
165+
<summary><b>How fast is it?</b></summary>
166+
167+
Native Rust core via [memvid](https://github.com/memvid/memvid). Sub-millisecond operations:
168+
169+
- Search: < 1ms for 10K+ memories
170+
- Insert: < 0.5ms
171+
- Load context: < 5ms
172+
173+
</details>
174+
175+
<details>
176+
<summary><b>Can I reset Claude's memory?</b></summary>
101177

102178
```bash
103-
/mind search "authentication" # find past context
104-
/mind ask "why postgres?" # ask your memory
105-
/mind recent # what happened lately
106-
/mind stats # how much is stored
179+
rm .claude/mind.mv2
107180
```
108181

109-
---
182+
Or use `/mind clear` (coming soon).
110183

111-
## FAQ
184+
</details>
112185

113-
**How big does the file get?**
114-
~1KB per memory. 1000 memories ≈ 1MB.
186+
<details>
187+
<summary><b>Does it work with multiple projects?</b></summary>
115188

116-
**Privacy?**
117-
Everything stays on your machine. Nothing uploaded.
189+
Yes! Each project gets its own `.claude/mind.mv2` file. Memories are project-scoped by default.
118190

119-
**Speed?**
120-
Native Rust core. Sub-millisecond operations.
121-
122-
**Reset?**
123-
Delete `.claude/mind.mv2` or run `/mind clear`.
191+
</details>
124192

125193
---
126194

127-
## Config (optional)
195+
## 🔧 Configuration (Optional)
196+
197+
Create `.claude/mind.config.json`:
128198

129199
```json
130200
{
@@ -134,12 +204,26 @@ Delete `.claude/mind.mv2` or run `/mind clear`.
134204
}
135205
```
136206

207+
Most users don't need to configure anything.
208+
137209
---
138210

211+
## 🤝 Contributing
212+
213+
We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
214+
215+
**Quick wins:**
216+
- Add to [awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills)
217+
- Star the repo ⭐
218+
- Share on Twitter/X with a demo
219+
220+
---
221+
222+
139223
<div align="center">
140224

141-
MIT License
225+
**MIT License** • Built on [memvid](https://github.com/memvid/memvid) — the single-file memory engine
142226

143-
Built on [memvid](https://github.com/Memvid/memvid) — the single-file memory engine.
227+
[Report Bug](https://github.com/memvid/memvid-mind/issues) • [Request Feature](https://github.com/memvid/memvid-mind/issues)
144228

145229
</div>

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "memvid-mind",
3-
"version": "1.0.5",
3+
"version": "1.0.6",
44
"description": "Give Claude Code photographic memory in ONE portable file",
55
"type": "module",
66
"main": "dist/index.js",

0 commit comments

Comments
 (0)