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.
@@ -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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """mnemo — local-first agent memory CLI."""
2
+
3
+ __version__ = "0.1.0"
4
+ __author__ = "Joshua Ndala"
File without changes