memvo 0.1.0a1__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.
- memvo-0.1.0a1/.gitignore +11 -0
- memvo-0.1.0a1/CHANGELOG.md +18 -0
- memvo-0.1.0a1/LICENSE +21 -0
- memvo-0.1.0a1/PKG-INFO +207 -0
- memvo-0.1.0a1/README.md +185 -0
- memvo-0.1.0a1/SECURITY.md +9 -0
- memvo-0.1.0a1/pyproject.toml +49 -0
- memvo-0.1.0a1/src/memvo/__init__.py +3 -0
- memvo-0.1.0a1/src/memvo/__main__.py +3 -0
- memvo-0.1.0a1/src/memvo/audit.py +73 -0
- memvo-0.1.0a1/src/memvo/cli.py +237 -0
- memvo-0.1.0a1/src/memvo/dates.py +88 -0
- memvo-0.1.0a1/src/memvo/importers/__init__.py +4 -0
- memvo-0.1.0a1/src/memvo/importers/csv_rows.py +168 -0
- memvo-0.1.0a1/src/memvo/importers/ofx_rows.py +90 -0
- memvo-0.1.0a1/src/memvo/mcp.py +233 -0
- memvo-0.1.0a1/src/memvo/money.py +89 -0
- memvo-0.1.0a1/src/memvo/reconcile.py +133 -0
- memvo-0.1.0a1/src/memvo/vault.py +445 -0
- memvo-0.1.0a1/tests/conftest.py +23 -0
- memvo-0.1.0a1/tests/fixtures/broken.csv +4 -0
- memvo-0.1.0a1/tests/fixtures/broker.csv +4 -0
- memvo-0.1.0a1/tests/fixtures/card.qfx +29 -0
- memvo-0.1.0a1/tests/fixtures/checking-nov.ofx +42 -0
- memvo-0.1.0a1/tests/fixtures/checking.csv +7 -0
- memvo-0.1.0a1/tests/fixtures/tabungan.csv +3 -0
- memvo-0.1.0a1/tests/test_cli.py +79 -0
- memvo-0.1.0a1/tests/test_import.py +71 -0
- memvo-0.1.0a1/tests/test_mcp.py +130 -0
- memvo-0.1.0a1/tests/test_money_dates.py +86 -0
- memvo-0.1.0a1/tests/test_ofx.py +120 -0
- memvo-0.1.0a1/tests/test_vault.py +135 -0
memvo-0.1.0a1/.gitignore
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
## 0.1.0a1 (2026-11-22)
|
|
6
|
+
|
|
7
|
+
First pre-release on PyPI. Pre-alpha: the vault schema may still change.
|
|
8
|
+
|
|
9
|
+
- CSV import with header detection (English and Indonesian column names),
|
|
10
|
+
sniffed separators, day/month order decided per file, multi-line records.
|
|
11
|
+
- Vault in one SQLite file: accounts, periods, verbatim entries, source hashes.
|
|
12
|
+
- `search` with full-text matching; every hit carries a receipt.
|
|
13
|
+
- `audit` re-hashes sources and checks each row against the file.
|
|
14
|
+
- `reconcile` checks running balances and an expected balance.
|
|
15
|
+
- OFX/QFX import (SGML and XML), bank transaction ids, statement ledger balance,
|
|
16
|
+
`reconcile --expect statement`, Windows-1252 fallback, vault schema 2 with
|
|
17
|
+
automatic migration from 1.
|
|
18
|
+
- `memvo mcp`: read-only MCP server on stdio with seven tools; results carry receipts.
|
memvo-0.1.0a1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Memvo contributors
|
|
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.
|
memvo-0.1.0a1/PKG-INFO
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: memvo
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Local-first financial memory for agents. Every answer comes with the line it came from.
|
|
5
|
+
Author: Memvo
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Keywords: bank-statements,finance,ledger,local-first,mcp,memory,reconciliation
|
|
9
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Topic :: Office/Business :: Financial :: Accounting
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
20
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Memvo
|
|
24
|
+
|
|
25
|
+
[memvo.pro](https://memvo.pro) · [X @MEMVOpro](https://x.com/MEMVOpro)
|
|
26
|
+
|
|
27
|
+
Local-first financial memory. Import your statements once, then ask about
|
|
28
|
+
your money and get the exact line each answer came from.
|
|
29
|
+
|
|
30
|
+
Memvo keeps every transaction verbatim, next to the SHA-256 of the file it
|
|
31
|
+
was read from. It never summarises, categorises with a model, or sends data
|
|
32
|
+
anywhere. Your vault is one SQLite file on your machine.
|
|
33
|
+
|
|
34
|
+
> **Status: pre-alpha.** Output above is from `tests/fixtures/checking.csv`. CSV import, search, audit and reconcile work and are
|
|
35
|
+
> tested, and agents can read the vault over MCP. PDF import and on-chain wallet import are not
|
|
36
|
+
> built yet. See [Status](#status).
|
|
37
|
+
|
|
38
|
+
## Why
|
|
39
|
+
|
|
40
|
+
Ask an assistant "what did I pay for that subscription in October?" and it
|
|
41
|
+
will often answer with a number it cannot show you. Memvo is built the other
|
|
42
|
+
way round: an answer is a stored row plus a receipt, or it is nothing.
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
$ memvo search streamly
|
|
46
|
+
2026-11-05 -17.99 checking STREAMLY SUBSCRIPTION, MONTHLY
|
|
47
|
+
e_87f7eaf199f9cde5 checking.csv:7
|
|
48
|
+
2026-10-05 -15.99 checking STREAMLY SUBSCRIPTION, MONTHLY
|
|
49
|
+
e_477cc512787183fc checking.csv:4
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
$ memvo show e_87f7eaf199f9cde5
|
|
54
|
+
e_87f7eaf199f9cde5
|
|
55
|
+
2026-11-05 -17.99 checking
|
|
56
|
+
STREAMLY SUBSCRIPTION, MONTHLY
|
|
57
|
+
|
|
58
|
+
receipt
|
|
59
|
+
source /home/me/statements/checking.csv (line 7)
|
|
60
|
+
file sha256 7e61003a02cb6628f28bcbd0e17aba1cef8d823813df4f95324ecfc53c8bdbdb
|
|
61
|
+
row sha256 6fe2f1f304317c9b9e6e96db7823ae80c72b38804c7ced445335d126a9a81ac5
|
|
62
|
+
raw 2026-11-05,"STREAMLY SUBSCRIPTION, MONTHLY",-17.99,4131.82
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## How the vault is laid out
|
|
66
|
+
|
|
67
|
+
```text
|
|
68
|
+
vault ── accounts ── periods (YYYY-MM) ── entries ── receipt
|
|
69
|
+
checking 2026-10 raw line, line range,
|
|
70
|
+
savings 2026-11 file sha256, row sha256
|
|
71
|
+
broker
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- **Entries are verbatim.** The `raw` field is the exact text from the file,
|
|
75
|
+
including quoted fields that span several lines.
|
|
76
|
+
- **IDs are deterministic.** An entry id is derived from the file hash, the
|
|
77
|
+
line number and the raw text, so importing the same file twice adds
|
|
78
|
+
nothing.
|
|
79
|
+
- **Amounts are exact.** Stored as integers scaled by 10,000. No floats.
|
|
80
|
+
|
|
81
|
+
## Install
|
|
82
|
+
|
|
83
|
+
Requires Python 3.10 or newer. No other dependencies.
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
pip install memvo # not yet published; for now: pip install -e .
|
|
87
|
+
memvo init
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The vault lives at `~/.memvo/vault.db`, or `$MEMVO_HOME/vault.db`, or wherever
|
|
91
|
+
`--vault` points.
|
|
92
|
+
|
|
93
|
+
## Use
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
memvo import ~/Downloads/checking.csv --account checking
|
|
97
|
+
memvo import mutasi.csv --account tabungan # ; separators, 1.234,56 amounts, debet/kredit columns
|
|
98
|
+
memvo import export.csv --account broker --kind broker --map amount=Net
|
|
99
|
+
memvo import download.qfx --account card # OFX/QFX is recognised from the content
|
|
100
|
+
|
|
101
|
+
memvo search rent # every hit carries its receipt
|
|
102
|
+
memvo search coffee --period 2026-11
|
|
103
|
+
memvo show e_87f7eaf199f9cde5
|
|
104
|
+
|
|
105
|
+
memvo accounts
|
|
106
|
+
memvo periods --account checking
|
|
107
|
+
|
|
108
|
+
memvo audit # re-hash every source, check every row
|
|
109
|
+
memvo reconcile --account checking --expect 4131.82
|
|
110
|
+
memvo reconcile --account checking --expect statement # use the ledger balance in the newest OFX
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Add `--json` to any command for machine-readable output.
|
|
114
|
+
|
|
115
|
+
### Import
|
|
116
|
+
|
|
117
|
+
Column detection reads the header and recognises common English and
|
|
118
|
+
Indonesian names (`Date`/`Tanggal`, `Amount`/`Jumlah`, `Debit`/`Debet`,
|
|
119
|
+
`Credit`/`Kredit`, `Balance`/`Saldo`, …). Use `--map role=Column` when it
|
|
120
|
+
guesses wrong. Separators are sniffed (`,` `;` tab `|`). Amount formats
|
|
121
|
+
handled: `1,234.56`, `1.234,56`, `1 234,56`, `(12.50)`, `12.50-`,
|
|
122
|
+
`IDR 1.500.000`. Day-first versus month-first is decided once per file by
|
|
123
|
+
looking at all its dates.
|
|
124
|
+
|
|
125
|
+
Rows that cannot be parsed are listed with their line number and reason. They
|
|
126
|
+
are never guessed.
|
|
127
|
+
|
|
128
|
+
OFX and QFX files (the "Download for Quicken/Money" option many banks offer)
|
|
129
|
+
are read in both the old SGML form and the XML form. Each `<STMTTRN>` block is
|
|
130
|
+
stored verbatim as one entry, its `FITID` is kept as the bank reference, and
|
|
131
|
+
the statement's ledger balance is remembered for `reconcile --expect statement`.
|
|
132
|
+
Overlapping downloads are matched on `FITID`. Files that are not UTF-8 are read
|
|
133
|
+
as Windows-1252.
|
|
134
|
+
|
|
135
|
+
### Audit
|
|
136
|
+
|
|
137
|
+
`memvo audit` re-reads every imported file. If the file hash still matches,
|
|
138
|
+
each entry's raw text is compared with the bytes on disk. A file that changed
|
|
139
|
+
or disappeared is reported as `CHANGED` or `MISSING`; its entries are kept as
|
|
140
|
+
they were imported. It also lists likely duplicates across overlapping
|
|
141
|
+
exports (same account, day, amount and text in two different files).
|
|
142
|
+
|
|
143
|
+
Exit code is `0` when everything matches and `2` when it does not, so it can
|
|
144
|
+
run in a cron job or CI.
|
|
145
|
+
|
|
146
|
+
### Reconcile
|
|
147
|
+
|
|
148
|
+
- **Running balance.** If a statement has a balance column, every row must
|
|
149
|
+
satisfy `previous balance + amount = balance`. A break points at a missing,
|
|
150
|
+
duplicated or misread row. Newest-first and oldest-first files both work.
|
|
151
|
+
- **Expected balance.** `--expect` compares the sum of entries (plus
|
|
152
|
+
`--opening`, up to `--as-of`) with a figure you read off a statement or a
|
|
153
|
+
wallet. `--expect statement` takes that figure from the newest imported
|
|
154
|
+
OFX ledger balance.
|
|
155
|
+
|
|
156
|
+
## Agents (MCP)
|
|
157
|
+
|
|
158
|
+
`memvo mcp` runs a Model Context Protocol server on stdio. Register it in any
|
|
159
|
+
MCP client:
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
{
|
|
163
|
+
"mcpServers": {
|
|
164
|
+
"memvo": { "command": "memvo", "args": ["mcp"] }
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Tools: `memvo_search`, `memvo_get_entry`, `memvo_accounts`, `memvo_periods`,
|
|
170
|
+
`memvo_audit`, `memvo_reconcile`, `memvo_stats`.
|
|
171
|
+
|
|
172
|
+
The server is read-only. An agent can search, inspect and check, but it
|
|
173
|
+
cannot import, edit or delete anything; importing stays a step you take
|
|
174
|
+
yourself. Every result that mentions an entry carries its receipt, and the
|
|
175
|
+
server tells the client to cite the source line instead of estimating.
|
|
176
|
+
|
|
177
|
+
## Status
|
|
178
|
+
|
|
179
|
+
| Feature | State |
|
|
180
|
+
|---|---|
|
|
181
|
+
| CSV import (bank, card, broker) | Live |
|
|
182
|
+
| Search with receipts | Live |
|
|
183
|
+
| Audit against source files | Live |
|
|
184
|
+
| Reconcile (running and expected balance) | Live |
|
|
185
|
+
| MCP server for agents (read-only) | Live |
|
|
186
|
+
| OFX / QFX import (1.x SGML and 2.x XML) | Live |
|
|
187
|
+
| PDF statement text import | Planned |
|
|
188
|
+
| Wallet import from a public address | Planned |
|
|
189
|
+
|
|
190
|
+
## Development
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
python -m venv .venv && . .venv/bin/activate
|
|
194
|
+
pip install -e '.[dev]'
|
|
195
|
+
pytest --cov
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Coverage must stay at or above 90%.
|
|
199
|
+
|
|
200
|
+
## Privacy
|
|
201
|
+
|
|
202
|
+
Memvo makes no network calls. Nothing is uploaded, and there is no
|
|
203
|
+
telemetry. Delete the vault file and the data is gone.
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
MIT
|
memvo-0.1.0a1/README.md
ADDED
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
# Memvo
|
|
2
|
+
|
|
3
|
+
[memvo.pro](https://memvo.pro) · [X @MEMVOpro](https://x.com/MEMVOpro)
|
|
4
|
+
|
|
5
|
+
Local-first financial memory. Import your statements once, then ask about
|
|
6
|
+
your money and get the exact line each answer came from.
|
|
7
|
+
|
|
8
|
+
Memvo keeps every transaction verbatim, next to the SHA-256 of the file it
|
|
9
|
+
was read from. It never summarises, categorises with a model, or sends data
|
|
10
|
+
anywhere. Your vault is one SQLite file on your machine.
|
|
11
|
+
|
|
12
|
+
> **Status: pre-alpha.** Output above is from `tests/fixtures/checking.csv`. CSV import, search, audit and reconcile work and are
|
|
13
|
+
> tested, and agents can read the vault over MCP. PDF import and on-chain wallet import are not
|
|
14
|
+
> built yet. See [Status](#status).
|
|
15
|
+
|
|
16
|
+
## Why
|
|
17
|
+
|
|
18
|
+
Ask an assistant "what did I pay for that subscription in October?" and it
|
|
19
|
+
will often answer with a number it cannot show you. Memvo is built the other
|
|
20
|
+
way round: an answer is a stored row plus a receipt, or it is nothing.
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
$ memvo search streamly
|
|
24
|
+
2026-11-05 -17.99 checking STREAMLY SUBSCRIPTION, MONTHLY
|
|
25
|
+
e_87f7eaf199f9cde5 checking.csv:7
|
|
26
|
+
2026-10-05 -15.99 checking STREAMLY SUBSCRIPTION, MONTHLY
|
|
27
|
+
e_477cc512787183fc checking.csv:4
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
$ memvo show e_87f7eaf199f9cde5
|
|
32
|
+
e_87f7eaf199f9cde5
|
|
33
|
+
2026-11-05 -17.99 checking
|
|
34
|
+
STREAMLY SUBSCRIPTION, MONTHLY
|
|
35
|
+
|
|
36
|
+
receipt
|
|
37
|
+
source /home/me/statements/checking.csv (line 7)
|
|
38
|
+
file sha256 7e61003a02cb6628f28bcbd0e17aba1cef8d823813df4f95324ecfc53c8bdbdb
|
|
39
|
+
row sha256 6fe2f1f304317c9b9e6e96db7823ae80c72b38804c7ced445335d126a9a81ac5
|
|
40
|
+
raw 2026-11-05,"STREAMLY SUBSCRIPTION, MONTHLY",-17.99,4131.82
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## How the vault is laid out
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
vault ── accounts ── periods (YYYY-MM) ── entries ── receipt
|
|
47
|
+
checking 2026-10 raw line, line range,
|
|
48
|
+
savings 2026-11 file sha256, row sha256
|
|
49
|
+
broker
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- **Entries are verbatim.** The `raw` field is the exact text from the file,
|
|
53
|
+
including quoted fields that span several lines.
|
|
54
|
+
- **IDs are deterministic.** An entry id is derived from the file hash, the
|
|
55
|
+
line number and the raw text, so importing the same file twice adds
|
|
56
|
+
nothing.
|
|
57
|
+
- **Amounts are exact.** Stored as integers scaled by 10,000. No floats.
|
|
58
|
+
|
|
59
|
+
## Install
|
|
60
|
+
|
|
61
|
+
Requires Python 3.10 or newer. No other dependencies.
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pip install memvo # not yet published; for now: pip install -e .
|
|
65
|
+
memvo init
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The vault lives at `~/.memvo/vault.db`, or `$MEMVO_HOME/vault.db`, or wherever
|
|
69
|
+
`--vault` points.
|
|
70
|
+
|
|
71
|
+
## Use
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
memvo import ~/Downloads/checking.csv --account checking
|
|
75
|
+
memvo import mutasi.csv --account tabungan # ; separators, 1.234,56 amounts, debet/kredit columns
|
|
76
|
+
memvo import export.csv --account broker --kind broker --map amount=Net
|
|
77
|
+
memvo import download.qfx --account card # OFX/QFX is recognised from the content
|
|
78
|
+
|
|
79
|
+
memvo search rent # every hit carries its receipt
|
|
80
|
+
memvo search coffee --period 2026-11
|
|
81
|
+
memvo show e_87f7eaf199f9cde5
|
|
82
|
+
|
|
83
|
+
memvo accounts
|
|
84
|
+
memvo periods --account checking
|
|
85
|
+
|
|
86
|
+
memvo audit # re-hash every source, check every row
|
|
87
|
+
memvo reconcile --account checking --expect 4131.82
|
|
88
|
+
memvo reconcile --account checking --expect statement # use the ledger balance in the newest OFX
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Add `--json` to any command for machine-readable output.
|
|
92
|
+
|
|
93
|
+
### Import
|
|
94
|
+
|
|
95
|
+
Column detection reads the header and recognises common English and
|
|
96
|
+
Indonesian names (`Date`/`Tanggal`, `Amount`/`Jumlah`, `Debit`/`Debet`,
|
|
97
|
+
`Credit`/`Kredit`, `Balance`/`Saldo`, …). Use `--map role=Column` when it
|
|
98
|
+
guesses wrong. Separators are sniffed (`,` `;` tab `|`). Amount formats
|
|
99
|
+
handled: `1,234.56`, `1.234,56`, `1 234,56`, `(12.50)`, `12.50-`,
|
|
100
|
+
`IDR 1.500.000`. Day-first versus month-first is decided once per file by
|
|
101
|
+
looking at all its dates.
|
|
102
|
+
|
|
103
|
+
Rows that cannot be parsed are listed with their line number and reason. They
|
|
104
|
+
are never guessed.
|
|
105
|
+
|
|
106
|
+
OFX and QFX files (the "Download for Quicken/Money" option many banks offer)
|
|
107
|
+
are read in both the old SGML form and the XML form. Each `<STMTTRN>` block is
|
|
108
|
+
stored verbatim as one entry, its `FITID` is kept as the bank reference, and
|
|
109
|
+
the statement's ledger balance is remembered for `reconcile --expect statement`.
|
|
110
|
+
Overlapping downloads are matched on `FITID`. Files that are not UTF-8 are read
|
|
111
|
+
as Windows-1252.
|
|
112
|
+
|
|
113
|
+
### Audit
|
|
114
|
+
|
|
115
|
+
`memvo audit` re-reads every imported file. If the file hash still matches,
|
|
116
|
+
each entry's raw text is compared with the bytes on disk. A file that changed
|
|
117
|
+
or disappeared is reported as `CHANGED` or `MISSING`; its entries are kept as
|
|
118
|
+
they were imported. It also lists likely duplicates across overlapping
|
|
119
|
+
exports (same account, day, amount and text in two different files).
|
|
120
|
+
|
|
121
|
+
Exit code is `0` when everything matches and `2` when it does not, so it can
|
|
122
|
+
run in a cron job or CI.
|
|
123
|
+
|
|
124
|
+
### Reconcile
|
|
125
|
+
|
|
126
|
+
- **Running balance.** If a statement has a balance column, every row must
|
|
127
|
+
satisfy `previous balance + amount = balance`. A break points at a missing,
|
|
128
|
+
duplicated or misread row. Newest-first and oldest-first files both work.
|
|
129
|
+
- **Expected balance.** `--expect` compares the sum of entries (plus
|
|
130
|
+
`--opening`, up to `--as-of`) with a figure you read off a statement or a
|
|
131
|
+
wallet. `--expect statement` takes that figure from the newest imported
|
|
132
|
+
OFX ledger balance.
|
|
133
|
+
|
|
134
|
+
## Agents (MCP)
|
|
135
|
+
|
|
136
|
+
`memvo mcp` runs a Model Context Protocol server on stdio. Register it in any
|
|
137
|
+
MCP client:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"mcpServers": {
|
|
142
|
+
"memvo": { "command": "memvo", "args": ["mcp"] }
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Tools: `memvo_search`, `memvo_get_entry`, `memvo_accounts`, `memvo_periods`,
|
|
148
|
+
`memvo_audit`, `memvo_reconcile`, `memvo_stats`.
|
|
149
|
+
|
|
150
|
+
The server is read-only. An agent can search, inspect and check, but it
|
|
151
|
+
cannot import, edit or delete anything; importing stays a step you take
|
|
152
|
+
yourself. Every result that mentions an entry carries its receipt, and the
|
|
153
|
+
server tells the client to cite the source line instead of estimating.
|
|
154
|
+
|
|
155
|
+
## Status
|
|
156
|
+
|
|
157
|
+
| Feature | State |
|
|
158
|
+
|---|---|
|
|
159
|
+
| CSV import (bank, card, broker) | Live |
|
|
160
|
+
| Search with receipts | Live |
|
|
161
|
+
| Audit against source files | Live |
|
|
162
|
+
| Reconcile (running and expected balance) | Live |
|
|
163
|
+
| MCP server for agents (read-only) | Live |
|
|
164
|
+
| OFX / QFX import (1.x SGML and 2.x XML) | Live |
|
|
165
|
+
| PDF statement text import | Planned |
|
|
166
|
+
| Wallet import from a public address | Planned |
|
|
167
|
+
|
|
168
|
+
## Development
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
python -m venv .venv && . .venv/bin/activate
|
|
172
|
+
pip install -e '.[dev]'
|
|
173
|
+
pytest --cov
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Coverage must stay at or above 90%.
|
|
177
|
+
|
|
178
|
+
## Privacy
|
|
179
|
+
|
|
180
|
+
Memvo makes no network calls. Nothing is uploaded, and there is no
|
|
181
|
+
telemetry. Delete the vault file and the data is gone.
|
|
182
|
+
|
|
183
|
+
## License
|
|
184
|
+
|
|
185
|
+
MIT
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
Memvo stores financial records on your own machine and makes no network
|
|
4
|
+
calls. If you find a way for it to leak, alter or lose data, please report
|
|
5
|
+
it privately through GitHub's "Report a vulnerability" button on this
|
|
6
|
+
repository instead of opening a public issue.
|
|
7
|
+
|
|
8
|
+
Include the Memvo version, your OS and Python version, and the steps or file
|
|
9
|
+
that reproduce the problem. Use made-up statements; never send real ones.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.25"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "memvo"
|
|
7
|
+
version = "0.1.0a1"
|
|
8
|
+
description = "Local-first financial memory for agents. Every answer comes with the line it came from."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Memvo" }]
|
|
14
|
+
keywords = ["finance", "ledger", "memory", "mcp", "bank-statements", "reconciliation", "local-first"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 2 - Pre-Alpha",
|
|
17
|
+
"Environment :: Console",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Intended Audience :: Financial and Insurance Industry",
|
|
20
|
+
"Operating System :: OS Independent",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
23
|
+
"Topic :: Office/Business :: Financial :: Accounting",
|
|
24
|
+
]
|
|
25
|
+
dependencies = []
|
|
26
|
+
|
|
27
|
+
[project.scripts]
|
|
28
|
+
memvo = "memvo.cli:main"
|
|
29
|
+
|
|
30
|
+
[project.optional-dependencies]
|
|
31
|
+
dev = ["pytest>=8", "pytest-cov>=5"]
|
|
32
|
+
|
|
33
|
+
[tool.hatch.build.targets.sdist]
|
|
34
|
+
exclude = ["/website", "/.github"]
|
|
35
|
+
|
|
36
|
+
[tool.hatch.build.targets.wheel]
|
|
37
|
+
packages = ["src/memvo"]
|
|
38
|
+
|
|
39
|
+
[tool.pytest.ini_options]
|
|
40
|
+
testpaths = ["tests"]
|
|
41
|
+
addopts = "-q"
|
|
42
|
+
|
|
43
|
+
[tool.coverage.run]
|
|
44
|
+
source = ["memvo"]
|
|
45
|
+
branch = true
|
|
46
|
+
|
|
47
|
+
[tool.coverage.report]
|
|
48
|
+
fail_under = 90
|
|
49
|
+
show_missing = true
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""Audit: prove that every stored entry still matches the file it came from.
|
|
2
|
+
|
|
3
|
+
For each source the file is re-read and re-hashed. If the hash matches, every
|
|
4
|
+
entry from it is checked line by line against the bytes on disk. If the file
|
|
5
|
+
changed or disappeared, its entries are reported, never silently rewritten.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from .vault import Vault, decode_text, sha256_bytes, sha256_text
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass
|
|
17
|
+
class SourceCheck:
|
|
18
|
+
source_id: int
|
|
19
|
+
path: str
|
|
20
|
+
status: str # ok | changed | missing
|
|
21
|
+
entries: int
|
|
22
|
+
mismatched: list[str] = field(default_factory=list)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass
|
|
26
|
+
class AuditReport:
|
|
27
|
+
sources: list[SourceCheck]
|
|
28
|
+
duplicates: list[list[str]]
|
|
29
|
+
|
|
30
|
+
@property
|
|
31
|
+
def ok(self) -> bool:
|
|
32
|
+
return all(s.status == "ok" and not s.mismatched for s in self.sources)
|
|
33
|
+
|
|
34
|
+
def as_dict(self) -> dict:
|
|
35
|
+
return {
|
|
36
|
+
"ok": self.ok,
|
|
37
|
+
"sources": [s.__dict__ for s in self.sources],
|
|
38
|
+
"possible_duplicates": self.duplicates,
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def audit(vault: Vault) -> AuditReport:
|
|
43
|
+
checks: list[SourceCheck] = []
|
|
44
|
+
for src in vault.sources():
|
|
45
|
+
rows = vault.db.execute(
|
|
46
|
+
"SELECT id, first_line, last_line, raw, raw_sha256 FROM entries WHERE source_id=? ORDER BY first_line",
|
|
47
|
+
(src["id"],),
|
|
48
|
+
).fetchall()
|
|
49
|
+
path = Path(src["path"])
|
|
50
|
+
if not path.exists():
|
|
51
|
+
checks.append(SourceCheck(src["id"], src["path"], "missing", len(rows)))
|
|
52
|
+
continue
|
|
53
|
+
data = path.read_bytes()
|
|
54
|
+
if sha256_bytes(data) != src["sha256"]:
|
|
55
|
+
checks.append(SourceCheck(src["id"], src["path"], "changed", len(rows)))
|
|
56
|
+
continue
|
|
57
|
+
lines = decode_text(data).splitlines(keepends=True)
|
|
58
|
+
bad = []
|
|
59
|
+
# CSV rows equal their line range; an OFX block may share a line with others.
|
|
60
|
+
for eid, first, last, raw, raw_sha in rows:
|
|
61
|
+
on_disk = "".join(lines[first - 1 : last]).rstrip("\r\n")
|
|
62
|
+
if raw not in on_disk or sha256_text(raw) != raw_sha:
|
|
63
|
+
bad.append(eid)
|
|
64
|
+
checks.append(SourceCheck(src["id"], src["path"], "ok", len(rows), bad))
|
|
65
|
+
|
|
66
|
+
dupes = [
|
|
67
|
+
ids.split(",")
|
|
68
|
+
for (ids,) in vault.db.execute(
|
|
69
|
+
"""SELECT GROUP_CONCAT(id) FROM entries GROUP BY fingerprint
|
|
70
|
+
HAVING COUNT(DISTINCT source_id) > 1 ORDER BY MIN(day)"""
|
|
71
|
+
)
|
|
72
|
+
]
|
|
73
|
+
return AuditReport(checks, dupes)
|