mnemo-agent 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mnemo_agent-0.1.0/LICENSE +21 -0
- mnemo_agent-0.1.0/PKG-INFO +319 -0
- mnemo_agent-0.1.0/README.md +275 -0
- mnemo_agent-0.1.0/pyproject.toml +52 -0
- mnemo_agent-0.1.0/setup.cfg +4 -0
- mnemo_agent-0.1.0/src/mnemo/__init__.py +4 -0
- mnemo_agent-0.1.0/src/mnemo/adapters/__init__.py +0 -0
- mnemo_agent-0.1.0/src/mnemo/adapters/letta_adapter.py +81 -0
- mnemo_agent-0.1.0/src/mnemo/adapters/mem0_adapter.py +69 -0
- mnemo_agent-0.1.0/src/mnemo/cli.py +912 -0
- mnemo_agent-0.1.0/src/mnemo/models.py +94 -0
- mnemo_agent-0.1.0/src/mnemo/search.py +99 -0
- mnemo_agent-0.1.0/src/mnemo/server.py +236 -0
- mnemo_agent-0.1.0/src/mnemo/storage.py +161 -0
- mnemo_agent-0.1.0/src/mnemo_agent.egg-info/PKG-INFO +319 -0
- mnemo_agent-0.1.0/src/mnemo_agent.egg-info/SOURCES.txt +19 -0
- mnemo_agent-0.1.0/src/mnemo_agent.egg-info/dependency_links.txt +1 -0
- mnemo_agent-0.1.0/src/mnemo_agent.egg-info/entry_points.txt +2 -0
- mnemo_agent-0.1.0/src/mnemo_agent.egg-info/requires.txt +29 -0
- mnemo_agent-0.1.0/src/mnemo_agent.egg-info/top_level.txt +1 -0
- mnemo_agent-0.1.0/tests/test_cli.py +340 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Joshua Ndala
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mnemo-agent
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Local-first agent memory CLI — dump, diff, migrate & query across Mem0, Letta, and more
|
|
5
|
+
Author: Joshua Ndala
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/joshndala/mnemo-agent
|
|
8
|
+
Project-URL: Repository, https://github.com/joshndala/mnemo-agent
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/joshndala/mnemo-agent/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/joshndala/mnemo-agent/CHANGELOG.md
|
|
11
|
+
Keywords: agent,memory,cli,mem0,letta,mcp
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Topic :: Utilities
|
|
17
|
+
Requires-Python: >=3.12
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: click>=8.1
|
|
21
|
+
Requires-Dist: pydantic>=2.6
|
|
22
|
+
Requires-Dist: rich>=13.7
|
|
23
|
+
Requires-Dist: fastapi>=0.110
|
|
24
|
+
Requires-Dist: uvicorn[standard]>=0.29
|
|
25
|
+
Requires-Dist: pyyaml>=6.0
|
|
26
|
+
Requires-Dist: python-dateutil>=2.9
|
|
27
|
+
Provides-Extra: mem0
|
|
28
|
+
Requires-Dist: mem0ai>=0.0.20; extra == "mem0"
|
|
29
|
+
Provides-Extra: letta
|
|
30
|
+
Requires-Dist: letta-client>=0.1; extra == "letta"
|
|
31
|
+
Provides-Extra: parquet
|
|
32
|
+
Requires-Dist: pyarrow>=16.0; extra == "parquet"
|
|
33
|
+
Requires-Dist: pandas>=2.2; extra == "parquet"
|
|
34
|
+
Provides-Extra: graph
|
|
35
|
+
Requires-Dist: networkx>=3.3; extra == "graph"
|
|
36
|
+
Requires-Dist: matplotlib>=3.9; extra == "graph"
|
|
37
|
+
Provides-Extra: all
|
|
38
|
+
Requires-Dist: mnemo[graph,letta,mem0,parquet]; extra == "all"
|
|
39
|
+
Provides-Extra: dev
|
|
40
|
+
Requires-Dist: pytest>=8.2; extra == "dev"
|
|
41
|
+
Requires-Dist: pytest-click>=1.1; extra == "dev"
|
|
42
|
+
Requires-Dist: httpx>=0.27; extra == "dev"
|
|
43
|
+
Dynamic: license-file
|
|
44
|
+
|
|
45
|
+
# 🧠 mnemo
|
|
46
|
+
|
|
47
|
+
> **Local-first agent memory CLI** — dump, diff, migrate, and query memories across [Mem0](https://mem0.ai), [Letta](https://letta.com), and your local filesystem.
|
|
48
|
+
|
|
49
|
+
Agents are finally getting good long‑term memory, but every framework (Mem0, Letta, Supermemory, custom Postgres) stores it differently. mnemo is a git‑like CLI for agent memory: you can dump, diff, migrate, and query what your agents know, all from your terminal, using a simple normalized schema and local‑first files. It’s designed for developers who want to own their agent’s “brain” instead of locking it into a single vendor.
|
|
50
|
+
|
|
51
|
+
Inspired by Mnemosyne (Greek goddess of memory), **mnemo** is a portable CLI for managing agent memory: capture facts, version-control dumps, compare snapshots, and sync to cloud memory providers — all from your terminal.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Features
|
|
56
|
+
|
|
57
|
+
- **11 CLI commands** with rich `--help` and tab-completion
|
|
58
|
+
- **Normalized schema** — facts with `{entity, attribute, value, source, timestamp, confidence}`
|
|
59
|
+
- **Multi-provider** — local JSON, Mem0, Letta (stubs → real APIs with optional deps)
|
|
60
|
+
- **TF-IDF search** — `mnemo recall "query"` with zero external ML deps
|
|
61
|
+
- **Rich tables** — confidence color-coded (🟢 ≥0.8, 🟡 ≥0.5, 🔴 <0.5)
|
|
62
|
+
- **HTML + graph diffs** — visual diff between dump snapshots
|
|
63
|
+
- **MCP server** — FastAPI `/mcp/list_tools` + `/mcp/call_tool` for Ollama/Claude Code agents
|
|
64
|
+
- **Safe writes** — `--dry-run` and `--approval` flags
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Quick Start
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Install
|
|
72
|
+
cd mnemo-agent
|
|
73
|
+
pip install -e . # core (local only)
|
|
74
|
+
pip install -e ".[all]" # everything (mem0 + letta + parquet + graph)
|
|
75
|
+
|
|
76
|
+
# Initialize Joshua's job-prep agent
|
|
77
|
+
mnemo init --agent job-prep
|
|
78
|
+
|
|
79
|
+
# Add facts manually (entity defaults to agent name, --tag is repeatable)
|
|
80
|
+
mnemo add --fact "Joshua uses React, Node, Supabase, Vercel" --agent job-prep
|
|
81
|
+
mnemo add --fact "Joshua is based in Toronto" --agent job-prep --confidence 1.0
|
|
82
|
+
mnemo add --fact "Chose Supabase over Firebase for auth" --agent job-prep --attribute decision --tag decision --tag auth
|
|
83
|
+
|
|
84
|
+
# View stored memories — plain format shows IDs for retract/edit
|
|
85
|
+
mnemo show --agent job-prep
|
|
86
|
+
mnemo show --agent job-prep --format plain
|
|
87
|
+
|
|
88
|
+
# Recall using natural language, optionally filtered by tag
|
|
89
|
+
mnemo recall "tech stack" --agent job-prep
|
|
90
|
+
mnemo recall "auth" --agent job-prep --tag decision
|
|
91
|
+
mnemo search "Supabase database" --agent job-prep --limit 5
|
|
92
|
+
|
|
93
|
+
# Edit or remove facts by ID (use 'show --format plain' to find IDs)
|
|
94
|
+
mnemo retract a1b2c3d4 --agent job-prep
|
|
95
|
+
mnemo edit a1b2c3d4 --value "Updated wording" --agent job-prep
|
|
96
|
+
|
|
97
|
+
# List all agents
|
|
98
|
+
mnemo ls --pretty
|
|
99
|
+
|
|
100
|
+
# Dump to a timestamped file
|
|
101
|
+
mnemo dump --agent job-prep
|
|
102
|
+
|
|
103
|
+
# Load a sample dump
|
|
104
|
+
mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
|
|
105
|
+
|
|
106
|
+
# Compare two agents (or two dump files)
|
|
107
|
+
mnemo diff --agent-a job-prep --agent-b job-prep-v2
|
|
108
|
+
mnemo diff dump1.json dump2.json --html diff_report.html
|
|
109
|
+
|
|
110
|
+
# Start the MCP server (for Ollama / Claude Code agents)
|
|
111
|
+
mnemo serve --agent job-prep --port 8080
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 📋 All Commands
|
|
117
|
+
|
|
118
|
+
| Command | Description |
|
|
119
|
+
|---|---|
|
|
120
|
+
| `mnemo init --agent <name>` | Initialize agent directory + config |
|
|
121
|
+
| `mnemo add --fact "text" --agent <name>` | Add a memory fact (`--entity`, `--attribute`, `--tag` supported) |
|
|
122
|
+
| `mnemo dump --agent <name> [--source mem0\|letta]` | Dump memories to JSON |
|
|
123
|
+
| `mnemo load --file dump.json --agent <name>` | Load dump into local/Mem0/Letta |
|
|
124
|
+
| `mnemo ls [--agent all]` | List agents and fact counts |
|
|
125
|
+
| `mnemo show --agent <name>` | Display agent's latest memories (`--format pretty\|json\|plain`) |
|
|
126
|
+
| `mnemo diff --agent-a <a> --agent-b <b>` | Diff two agents (or `diff a.json b.json`) |
|
|
127
|
+
| `mnemo recall "query" [--tag <tag>]` | TF-IDF search across all agents, optional tag filter |
|
|
128
|
+
| `mnemo search "query" [--limit 10] [--tag <tag>]` | Alias for recall with higher default limit |
|
|
129
|
+
| `mnemo retract <fact-id> --agent <name>` | Remove a fact by ID or 8-char prefix |
|
|
130
|
+
| `mnemo edit <fact-id> --agent <name>` | Edit value/attribute/confidence of an existing fact |
|
|
131
|
+
| `mnemo migrate --dump f.json --target mem0 --agent name` | Migrate between providers |
|
|
132
|
+
| `mnemo serve --agent <name> [--port 8080] [--read-only]` | MCP FastAPI server |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Project Structure
|
|
137
|
+
|
|
138
|
+
```
|
|
139
|
+
mnemo-agent/
|
|
140
|
+
├── src/mnemo/
|
|
141
|
+
│ ├── __init__.py # version
|
|
142
|
+
│ ├── cli.py # Click CLI (all commands)
|
|
143
|
+
│ ├── models.py # Pydantic: Fact, AgentDump, MnemoConfig
|
|
144
|
+
│ ├── storage.py # Local file I/O (JSON, YAML, Parquet)
|
|
145
|
+
│ ├── search.py # TF-IDF search + diff engine
|
|
146
|
+
│ ├── server.py # FastAPI MCP server
|
|
147
|
+
│ └── adapters/
|
|
148
|
+
│ ├── mem0_adapter.py # Mem0 API → normalized facts
|
|
149
|
+
│ └── letta_adapter.py # Letta API → normalized facts
|
|
150
|
+
├── tests/
|
|
151
|
+
│ ├── test_cli.py # pytest suite
|
|
152
|
+
│ └── fixtures/
|
|
153
|
+
│ └── job_prep_sample.json
|
|
154
|
+
├── config.yaml # Sample agent config
|
|
155
|
+
├── pyproject.toml
|
|
156
|
+
└── requirements.txt
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Memory Schema
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"agent": "job-prep",
|
|
166
|
+
"dump_ts": "2026-03-21T23:00Z",
|
|
167
|
+
"source": "manual",
|
|
168
|
+
"version": "1",
|
|
169
|
+
"facts": [
|
|
170
|
+
{
|
|
171
|
+
"id": "uuid",
|
|
172
|
+
"entity": "Joshua",
|
|
173
|
+
"attribute": "tech_stack",
|
|
174
|
+
"value": "React, Node, Supabase, Vercel",
|
|
175
|
+
"source": "chat|tool|manual|mem0|letta|import",
|
|
176
|
+
"timestamp": "2026-03-21T20:00Z",
|
|
177
|
+
"confidence": 0.95,
|
|
178
|
+
"metadata": {}
|
|
179
|
+
}
|
|
180
|
+
]
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Example: Project Memory for `advisor-prep`
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"agent": "advisor-prep",
|
|
189
|
+
"facts": [
|
|
190
|
+
{
|
|
191
|
+
"id": "uuid-1",
|
|
192
|
+
"entity": "advisor-prep-agent",
|
|
193
|
+
"attribute": "project_summary",
|
|
194
|
+
"value": "CLI + agent that helps students prep for advisor meetings using UBC context.",
|
|
195
|
+
"source": "manual",
|
|
196
|
+
"timestamp": "2026-03-22T01:00Z",
|
|
197
|
+
"confidence": 0.9,
|
|
198
|
+
"metadata": { "tags": ["summary", "high-level"] }
|
|
199
|
+
},
|
|
200
|
+
{
|
|
201
|
+
"id": "uuid-2",
|
|
202
|
+
"entity": "advisor-prep-agent",
|
|
203
|
+
"attribute": "decision",
|
|
204
|
+
"value": "Chose Supabase over Firebase for auth due to better Postgres integration.",
|
|
205
|
+
"source": "manual",
|
|
206
|
+
"timestamp": "2026-03-22T01:05Z",
|
|
207
|
+
"confidence": 0.95,
|
|
208
|
+
"metadata": { "tags": ["decision", "auth"], "ticket": "ADR-001" }
|
|
209
|
+
},
|
|
210
|
+
{
|
|
211
|
+
"id": "uuid-3",
|
|
212
|
+
"entity": "advisor-prep-agent",
|
|
213
|
+
"attribute": "stack",
|
|
214
|
+
"value": "Next.js, React, Node, Supabase, Vercel.",
|
|
215
|
+
"source": "manual",
|
|
216
|
+
"timestamp": "2026-03-22T01:10Z",
|
|
217
|
+
"confidence": 1.0,
|
|
218
|
+
"metadata": { "tags": ["stack"] }
|
|
219
|
+
}
|
|
220
|
+
]
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## 🔌 MCP Server (for Ollama / Claude Code)
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
mnemo serve --agent job-prep --port 8080
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
| Endpoint | Description |
|
|
233
|
+
|---|---|
|
|
234
|
+
| `GET /mcp/list_tools` | List available tools (MCP schema) |
|
|
235
|
+
| `POST /mcp/call_tool` | Call a tool by name with arguments |
|
|
236
|
+
| `GET /facts` | REST: list all facts |
|
|
237
|
+
| `GET /search?q=query` | REST: search memories |
|
|
238
|
+
| `GET /docs` | Swagger UI |
|
|
239
|
+
|
|
240
|
+
### Available MCP tools
|
|
241
|
+
|
|
242
|
+
```json
|
|
243
|
+
{ "name": "search_memory", "description": "TF-IDF search over agent memory" }
|
|
244
|
+
{ "name": "list_facts", "description": "Return all facts, optionally filtered" }
|
|
245
|
+
{ "name": "upsert_fact", "description": "Add a fact to agent memory" }
|
|
246
|
+
{ "name": "get_agent_info", "description": "Agent metadata and fact count" }
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## ⚙️ Configuration
|
|
252
|
+
|
|
253
|
+
Each agent has `~/.mnemo/<agent>/config.yaml`:
|
|
254
|
+
|
|
255
|
+
```yaml
|
|
256
|
+
agent: job-prep
|
|
257
|
+
default_source: local
|
|
258
|
+
default_target: local
|
|
259
|
+
mem0_api_key: null # https://app.mem0.ai
|
|
260
|
+
mem0_user_id: joshua
|
|
261
|
+
letta_base_url: http://localhost:8283
|
|
262
|
+
letta_agent_id: null # from your Letta agent
|
|
263
|
+
tags: [job-prep, interview]
|
|
264
|
+
notes: Memory store for interview prep agent
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## Environment Variables
|
|
270
|
+
|
|
271
|
+
| Variable | Description |
|
|
272
|
+
|---|---|
|
|
273
|
+
| `MNEMO_AGENT` | Default agent name (skips `--agent` flag) |
|
|
274
|
+
| `MNEMO_DIR` | Override base directory (default: `~/.mnemo`) |
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Tests
|
|
279
|
+
|
|
280
|
+
```bash
|
|
281
|
+
pip install -e ".[dev]"
|
|
282
|
+
pytest tests/ -v
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## Roadmap
|
|
288
|
+
|
|
289
|
+
- [ ] Vector embeddings for semantic search (v2)
|
|
290
|
+
- [ ] Parquet export for analytics
|
|
291
|
+
- [ ] `mnemo audit` — fact provenance trace
|
|
292
|
+
- [ ] Web UI dashboard
|
|
293
|
+
- [ ] Native Ollama MCP client registration
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## Example Use Case: `job-prep` Agent
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
# Bootstrap your interview prep memory
|
|
301
|
+
mnemo init --agent job-prep
|
|
302
|
+
mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
|
|
303
|
+
|
|
304
|
+
# Ask your agent questions via MCP (Ollama / Claude Code reads from :8080)
|
|
305
|
+
mnemo serve --agent job-prep --port 8080
|
|
306
|
+
|
|
307
|
+
# After a practice interview, add what you learned
|
|
308
|
+
mnemo add --fact "Lead with Supabase migration story at FAANG interviews" \
|
|
309
|
+
--agent job-prep --attribute interview_tip --confidence 0.9 --tag tip
|
|
310
|
+
|
|
311
|
+
# Before next session, recall relevant context
|
|
312
|
+
mnemo recall "React Supabase full-stack" --agent job-prep
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## License
|
|
318
|
+
|
|
319
|
+
MIT © Joshua Ndala
|
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
# 🧠 mnemo
|
|
2
|
+
|
|
3
|
+
> **Local-first agent memory CLI** — dump, diff, migrate, and query memories across [Mem0](https://mem0.ai), [Letta](https://letta.com), and your local filesystem.
|
|
4
|
+
|
|
5
|
+
Agents are finally getting good long‑term memory, but every framework (Mem0, Letta, Supermemory, custom Postgres) stores it differently. mnemo is a git‑like CLI for agent memory: you can dump, diff, migrate, and query what your agents know, all from your terminal, using a simple normalized schema and local‑first files. It’s designed for developers who want to own their agent’s “brain” instead of locking it into a single vendor.
|
|
6
|
+
|
|
7
|
+
Inspired by Mnemosyne (Greek goddess of memory), **mnemo** is a portable CLI for managing agent memory: capture facts, version-control dumps, compare snapshots, and sync to cloud memory providers — all from your terminal.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- **11 CLI commands** with rich `--help` and tab-completion
|
|
14
|
+
- **Normalized schema** — facts with `{entity, attribute, value, source, timestamp, confidence}`
|
|
15
|
+
- **Multi-provider** — local JSON, Mem0, Letta (stubs → real APIs with optional deps)
|
|
16
|
+
- **TF-IDF search** — `mnemo recall "query"` with zero external ML deps
|
|
17
|
+
- **Rich tables** — confidence color-coded (🟢 ≥0.8, 🟡 ≥0.5, 🔴 <0.5)
|
|
18
|
+
- **HTML + graph diffs** — visual diff between dump snapshots
|
|
19
|
+
- **MCP server** — FastAPI `/mcp/list_tools` + `/mcp/call_tool` for Ollama/Claude Code agents
|
|
20
|
+
- **Safe writes** — `--dry-run` and `--approval` flags
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Quick Start
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# Install
|
|
28
|
+
cd mnemo-agent
|
|
29
|
+
pip install -e . # core (local only)
|
|
30
|
+
pip install -e ".[all]" # everything (mem0 + letta + parquet + graph)
|
|
31
|
+
|
|
32
|
+
# Initialize Joshua's job-prep agent
|
|
33
|
+
mnemo init --agent job-prep
|
|
34
|
+
|
|
35
|
+
# Add facts manually (entity defaults to agent name, --tag is repeatable)
|
|
36
|
+
mnemo add --fact "Joshua uses React, Node, Supabase, Vercel" --agent job-prep
|
|
37
|
+
mnemo add --fact "Joshua is based in Toronto" --agent job-prep --confidence 1.0
|
|
38
|
+
mnemo add --fact "Chose Supabase over Firebase for auth" --agent job-prep --attribute decision --tag decision --tag auth
|
|
39
|
+
|
|
40
|
+
# View stored memories — plain format shows IDs for retract/edit
|
|
41
|
+
mnemo show --agent job-prep
|
|
42
|
+
mnemo show --agent job-prep --format plain
|
|
43
|
+
|
|
44
|
+
# Recall using natural language, optionally filtered by tag
|
|
45
|
+
mnemo recall "tech stack" --agent job-prep
|
|
46
|
+
mnemo recall "auth" --agent job-prep --tag decision
|
|
47
|
+
mnemo search "Supabase database" --agent job-prep --limit 5
|
|
48
|
+
|
|
49
|
+
# Edit or remove facts by ID (use 'show --format plain' to find IDs)
|
|
50
|
+
mnemo retract a1b2c3d4 --agent job-prep
|
|
51
|
+
mnemo edit a1b2c3d4 --value "Updated wording" --agent job-prep
|
|
52
|
+
|
|
53
|
+
# List all agents
|
|
54
|
+
mnemo ls --pretty
|
|
55
|
+
|
|
56
|
+
# Dump to a timestamped file
|
|
57
|
+
mnemo dump --agent job-prep
|
|
58
|
+
|
|
59
|
+
# Load a sample dump
|
|
60
|
+
mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
|
|
61
|
+
|
|
62
|
+
# Compare two agents (or two dump files)
|
|
63
|
+
mnemo diff --agent-a job-prep --agent-b job-prep-v2
|
|
64
|
+
mnemo diff dump1.json dump2.json --html diff_report.html
|
|
65
|
+
|
|
66
|
+
# Start the MCP server (for Ollama / Claude Code agents)
|
|
67
|
+
mnemo serve --agent job-prep --port 8080
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 📋 All Commands
|
|
73
|
+
|
|
74
|
+
| Command | Description |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `mnemo init --agent <name>` | Initialize agent directory + config |
|
|
77
|
+
| `mnemo add --fact "text" --agent <name>` | Add a memory fact (`--entity`, `--attribute`, `--tag` supported) |
|
|
78
|
+
| `mnemo dump --agent <name> [--source mem0\|letta]` | Dump memories to JSON |
|
|
79
|
+
| `mnemo load --file dump.json --agent <name>` | Load dump into local/Mem0/Letta |
|
|
80
|
+
| `mnemo ls [--agent all]` | List agents and fact counts |
|
|
81
|
+
| `mnemo show --agent <name>` | Display agent's latest memories (`--format pretty\|json\|plain`) |
|
|
82
|
+
| `mnemo diff --agent-a <a> --agent-b <b>` | Diff two agents (or `diff a.json b.json`) |
|
|
83
|
+
| `mnemo recall "query" [--tag <tag>]` | TF-IDF search across all agents, optional tag filter |
|
|
84
|
+
| `mnemo search "query" [--limit 10] [--tag <tag>]` | Alias for recall with higher default limit |
|
|
85
|
+
| `mnemo retract <fact-id> --agent <name>` | Remove a fact by ID or 8-char prefix |
|
|
86
|
+
| `mnemo edit <fact-id> --agent <name>` | Edit value/attribute/confidence of an existing fact |
|
|
87
|
+
| `mnemo migrate --dump f.json --target mem0 --agent name` | Migrate between providers |
|
|
88
|
+
| `mnemo serve --agent <name> [--port 8080] [--read-only]` | MCP FastAPI server |
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Project Structure
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
mnemo-agent/
|
|
96
|
+
├── src/mnemo/
|
|
97
|
+
│ ├── __init__.py # version
|
|
98
|
+
│ ├── cli.py # Click CLI (all commands)
|
|
99
|
+
│ ├── models.py # Pydantic: Fact, AgentDump, MnemoConfig
|
|
100
|
+
│ ├── storage.py # Local file I/O (JSON, YAML, Parquet)
|
|
101
|
+
│ ├── search.py # TF-IDF search + diff engine
|
|
102
|
+
│ ├── server.py # FastAPI MCP server
|
|
103
|
+
│ └── adapters/
|
|
104
|
+
│ ├── mem0_adapter.py # Mem0 API → normalized facts
|
|
105
|
+
│ └── letta_adapter.py # Letta API → normalized facts
|
|
106
|
+
├── tests/
|
|
107
|
+
│ ├── test_cli.py # pytest suite
|
|
108
|
+
│ └── fixtures/
|
|
109
|
+
│ └── job_prep_sample.json
|
|
110
|
+
├── config.yaml # Sample agent config
|
|
111
|
+
├── pyproject.toml
|
|
112
|
+
└── requirements.txt
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Memory Schema
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"agent": "job-prep",
|
|
122
|
+
"dump_ts": "2026-03-21T23:00Z",
|
|
123
|
+
"source": "manual",
|
|
124
|
+
"version": "1",
|
|
125
|
+
"facts": [
|
|
126
|
+
{
|
|
127
|
+
"id": "uuid",
|
|
128
|
+
"entity": "Joshua",
|
|
129
|
+
"attribute": "tech_stack",
|
|
130
|
+
"value": "React, Node, Supabase, Vercel",
|
|
131
|
+
"source": "chat|tool|manual|mem0|letta|import",
|
|
132
|
+
"timestamp": "2026-03-21T20:00Z",
|
|
133
|
+
"confidence": 0.95,
|
|
134
|
+
"metadata": {}
|
|
135
|
+
}
|
|
136
|
+
]
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Example: Project Memory for `advisor-prep`
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"agent": "advisor-prep",
|
|
145
|
+
"facts": [
|
|
146
|
+
{
|
|
147
|
+
"id": "uuid-1",
|
|
148
|
+
"entity": "advisor-prep-agent",
|
|
149
|
+
"attribute": "project_summary",
|
|
150
|
+
"value": "CLI + agent that helps students prep for advisor meetings using UBC context.",
|
|
151
|
+
"source": "manual",
|
|
152
|
+
"timestamp": "2026-03-22T01:00Z",
|
|
153
|
+
"confidence": 0.9,
|
|
154
|
+
"metadata": { "tags": ["summary", "high-level"] }
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
"id": "uuid-2",
|
|
158
|
+
"entity": "advisor-prep-agent",
|
|
159
|
+
"attribute": "decision",
|
|
160
|
+
"value": "Chose Supabase over Firebase for auth due to better Postgres integration.",
|
|
161
|
+
"source": "manual",
|
|
162
|
+
"timestamp": "2026-03-22T01:05Z",
|
|
163
|
+
"confidence": 0.95,
|
|
164
|
+
"metadata": { "tags": ["decision", "auth"], "ticket": "ADR-001" }
|
|
165
|
+
},
|
|
166
|
+
{
|
|
167
|
+
"id": "uuid-3",
|
|
168
|
+
"entity": "advisor-prep-agent",
|
|
169
|
+
"attribute": "stack",
|
|
170
|
+
"value": "Next.js, React, Node, Supabase, Vercel.",
|
|
171
|
+
"source": "manual",
|
|
172
|
+
"timestamp": "2026-03-22T01:10Z",
|
|
173
|
+
"confidence": 1.0,
|
|
174
|
+
"metadata": { "tags": ["stack"] }
|
|
175
|
+
}
|
|
176
|
+
]
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 🔌 MCP Server (for Ollama / Claude Code)
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
mnemo serve --agent job-prep --port 8080
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
| Endpoint | Description |
|
|
189
|
+
|---|---|
|
|
190
|
+
| `GET /mcp/list_tools` | List available tools (MCP schema) |
|
|
191
|
+
| `POST /mcp/call_tool` | Call a tool by name with arguments |
|
|
192
|
+
| `GET /facts` | REST: list all facts |
|
|
193
|
+
| `GET /search?q=query` | REST: search memories |
|
|
194
|
+
| `GET /docs` | Swagger UI |
|
|
195
|
+
|
|
196
|
+
### Available MCP tools
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{ "name": "search_memory", "description": "TF-IDF search over agent memory" }
|
|
200
|
+
{ "name": "list_facts", "description": "Return all facts, optionally filtered" }
|
|
201
|
+
{ "name": "upsert_fact", "description": "Add a fact to agent memory" }
|
|
202
|
+
{ "name": "get_agent_info", "description": "Agent metadata and fact count" }
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## ⚙️ Configuration
|
|
208
|
+
|
|
209
|
+
Each agent has `~/.mnemo/<agent>/config.yaml`:
|
|
210
|
+
|
|
211
|
+
```yaml
|
|
212
|
+
agent: job-prep
|
|
213
|
+
default_source: local
|
|
214
|
+
default_target: local
|
|
215
|
+
mem0_api_key: null # https://app.mem0.ai
|
|
216
|
+
mem0_user_id: joshua
|
|
217
|
+
letta_base_url: http://localhost:8283
|
|
218
|
+
letta_agent_id: null # from your Letta agent
|
|
219
|
+
tags: [job-prep, interview]
|
|
220
|
+
notes: Memory store for interview prep agent
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## Environment Variables
|
|
226
|
+
|
|
227
|
+
| Variable | Description |
|
|
228
|
+
|---|---|
|
|
229
|
+
| `MNEMO_AGENT` | Default agent name (skips `--agent` flag) |
|
|
230
|
+
| `MNEMO_DIR` | Override base directory (default: `~/.mnemo`) |
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Tests
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
pip install -e ".[dev]"
|
|
238
|
+
pytest tests/ -v
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## Roadmap
|
|
244
|
+
|
|
245
|
+
- [ ] Vector embeddings for semantic search (v2)
|
|
246
|
+
- [ ] Parquet export for analytics
|
|
247
|
+
- [ ] `mnemo audit` — fact provenance trace
|
|
248
|
+
- [ ] Web UI dashboard
|
|
249
|
+
- [ ] Native Ollama MCP client registration
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Example Use Case: `job-prep` Agent
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
# Bootstrap your interview prep memory
|
|
257
|
+
mnemo init --agent job-prep
|
|
258
|
+
mnemo load --file tests/fixtures/job_prep_sample.json --agent job-prep
|
|
259
|
+
|
|
260
|
+
# Ask your agent questions via MCP (Ollama / Claude Code reads from :8080)
|
|
261
|
+
mnemo serve --agent job-prep --port 8080
|
|
262
|
+
|
|
263
|
+
# After a practice interview, add what you learned
|
|
264
|
+
mnemo add --fact "Lead with Supabase migration story at FAANG interviews" \
|
|
265
|
+
--agent job-prep --attribute interview_tip --confidence 0.9 --tag tip
|
|
266
|
+
|
|
267
|
+
# Before next session, recall relevant context
|
|
268
|
+
mnemo recall "React Supabase full-stack" --agent job-prep
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## License
|
|
274
|
+
|
|
275
|
+
MIT © Joshua Ndala
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "mnemo-agent"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Local-first agent memory CLI — dump, diff, migrate & query across Mem0, Letta, and more"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{ name = "Joshua Ndala" }]
|
|
13
|
+
keywords = ["agent", "memory", "cli", "mem0", "letta", "mcp"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Topic :: Utilities",
|
|
20
|
+
]
|
|
21
|
+
dependencies = [
|
|
22
|
+
"click>=8.1",
|
|
23
|
+
"pydantic>=2.6",
|
|
24
|
+
"rich>=13.7",
|
|
25
|
+
"fastapi>=0.110",
|
|
26
|
+
"uvicorn[standard]>=0.29",
|
|
27
|
+
"pyyaml>=6.0",
|
|
28
|
+
"python-dateutil>=2.9",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
mem0 = ["mem0ai>=0.0.20"]
|
|
33
|
+
letta = ["letta-client>=0.1"]
|
|
34
|
+
parquet = ["pyarrow>=16.0", "pandas>=2.2"]
|
|
35
|
+
graph = ["networkx>=3.3", "matplotlib>=3.9"]
|
|
36
|
+
all = ["mnemo[mem0,letta,parquet,graph]"]
|
|
37
|
+
dev = ["pytest>=8.2", "pytest-click>=1.1", "httpx>=0.27"]
|
|
38
|
+
|
|
39
|
+
[project.urls]
|
|
40
|
+
Homepage = "https://github.com/joshndala/mnemo-agent"
|
|
41
|
+
Repository = "https://github.com/joshndala/mnemo-agent"
|
|
42
|
+
"Bug Tracker" = "https://github.com/joshndala/mnemo-agent/issues"
|
|
43
|
+
Changelog = "https://github.com/joshndala/mnemo-agent/CHANGELOG.md"
|
|
44
|
+
|
|
45
|
+
[project.scripts]
|
|
46
|
+
mnemo = "mnemo.cli:cli"
|
|
47
|
+
|
|
48
|
+
[tool.setuptools.packages.find]
|
|
49
|
+
where = ["src"]
|
|
50
|
+
|
|
51
|
+
[tool.pytest.ini_options]
|
|
52
|
+
testpaths = ["tests"]
|
|
File without changes
|