eviloomemvault 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.
- eviloomemvault-0.1.0/.dockerignore +9 -0
- eviloomemvault-0.1.0/.env.example +15 -0
- eviloomemvault-0.1.0/.github/workflows/ci.yml +28 -0
- eviloomemvault-0.1.0/.github/workflows/release.yaml +36 -0
- eviloomemvault-0.1.0/.gitignore +12 -0
- eviloomemvault-0.1.0/LICENSE +21 -0
- eviloomemvault-0.1.0/PKG-INFO +260 -0
- eviloomemvault-0.1.0/README.md +236 -0
- eviloomemvault-0.1.0/docker/docker-compose.yml +46 -0
- eviloomemvault-0.1.0/docker/dockerfile +28 -0
- eviloomemvault-0.1.0/docs/architecture.md +101 -0
- eviloomemvault-0.1.0/docs/contributing.md +51 -0
- eviloomemvault-0.1.0/docs/getting-started.md +253 -0
- eviloomemvault-0.1.0/examples/agent_integration.py +117 -0
- eviloomemvault-0.1.0/examples/basic_usage.py +91 -0
- eviloomemvault-0.1.0/pyproject.toml +60 -0
- eviloomemvault-0.1.0/src/memvault/__init__.py +26 -0
- eviloomemvault-0.1.0/src/memvault/api/__init__.py +0 -0
- eviloomemvault-0.1.0/src/memvault/api/app.py +59 -0
- eviloomemvault-0.1.0/src/memvault/api/dependencies.py +28 -0
- eviloomemvault-0.1.0/src/memvault/api/routes.py +207 -0
- eviloomemvault-0.1.0/src/memvault/api/schemas.py +98 -0
- eviloomemvault-0.1.0/src/memvault/cli/__init__.py +0 -0
- eviloomemvault-0.1.0/src/memvault/cli/main.py +193 -0
- eviloomemvault-0.1.0/src/memvault/core/__init__.py +0 -0
- eviloomemvault-0.1.0/src/memvault/core/consolidation.py +166 -0
- eviloomemvault-0.1.0/src/memvault/core/models.py +66 -0
- eviloomemvault-0.1.0/src/memvault/core/retrieval.py +126 -0
- eviloomemvault-0.1.0/src/memvault/core/scoring.py +135 -0
- eviloomemvault-0.1.0/src/memvault/embeddings/__init__.py +0 -0
- eviloomemvault-0.1.0/src/memvault/embeddings/base.py +34 -0
- eviloomemvault-0.1.0/src/memvault/embeddings/local.py +48 -0
- eviloomemvault-0.1.0/src/memvault/embeddings/provider.py +18 -0
- eviloomemvault-0.1.0/src/memvault/memvault.py +260 -0
- eviloomemvault-0.1.0/src/memvault/observability/__init__.py +0 -0
- eviloomemvault-0.1.0/src/memvault/observability/logging.py +46 -0
- eviloomemvault-0.1.0/src/memvault/observability/metrics.py +56 -0
- eviloomemvault-0.1.0/src/memvault/storage/__init__.py +0 -0
- eviloomemvault-0.1.0/src/memvault/storage/base.py +107 -0
- eviloomemvault-0.1.0/src/memvault/storage/memory.py +70 -0
- eviloomemvault-0.1.0/src/memvault/storage/postgres.py +216 -0
- eviloomemvault-0.1.0/src/memvault/storage/sqlite.py +187 -0
- eviloomemvault-0.1.0/tests/test_api.py +181 -0
- eviloomemvault-0.1.0/tests/test_consolidation.py +158 -0
- eviloomemvault-0.1.0/tests/test_decay_reinforcement.py +92 -0
- eviloomemvault-0.1.0/tests/test_embeddings.py +72 -0
- eviloomemvault-0.1.0/tests/test_models.py +67 -0
- eviloomemvault-0.1.0/tests/test_retrieval.py +134 -0
- eviloomemvault-0.1.0/tests/test_scoring.py +95 -0
- eviloomemvault-0.1.0/tests/test_storage_contract.py +221 -0
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Copy this file to .env and fill in your values
|
|
2
|
+
# cp .env.example .env
|
|
3
|
+
|
|
4
|
+
# Database path for the API server
|
|
5
|
+
DB_PATH=memories.db
|
|
6
|
+
|
|
7
|
+
# Set to 1 if BGE model is already cached locally (faster startup, no HF Hub calls)
|
|
8
|
+
HF_HUB_OFFLINE=1
|
|
9
|
+
|
|
10
|
+
# Log level: DEBUG, INFO, WARNING, ERROR
|
|
11
|
+
LOG_LEVEL=INFO
|
|
12
|
+
|
|
13
|
+
# Postgres DSN for running contract tests against PostgreSQL
|
|
14
|
+
# Start postgres with: docker compose -f docker/docker-compose.yml up postgres -d
|
|
15
|
+
TEST_POSTGRES_DSN=postgresql://memvault:memvault@localhost:5433/memvault
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
|
|
16
|
+
- name: Set up Python
|
|
17
|
+
uses: actions/setup-python@v5
|
|
18
|
+
with:
|
|
19
|
+
python-version: "3.10"
|
|
20
|
+
|
|
21
|
+
- name: Install dependencies
|
|
22
|
+
run: pip install -e ".[local,dev]"
|
|
23
|
+
|
|
24
|
+
- name: Lint with ruff
|
|
25
|
+
run: ruff check .
|
|
26
|
+
|
|
27
|
+
- name: Run tests
|
|
28
|
+
run: pytest -v --tb=short
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
release:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
|
|
12
|
+
steps:
|
|
13
|
+
- uses: actions/checkout@v4
|
|
14
|
+
|
|
15
|
+
- name: Set up Python
|
|
16
|
+
uses: actions/setup-python@v5
|
|
17
|
+
with:
|
|
18
|
+
python-version: "3.10"
|
|
19
|
+
|
|
20
|
+
- name: Install build tools
|
|
21
|
+
run: pip install build twine
|
|
22
|
+
|
|
23
|
+
- name: Install dependencies
|
|
24
|
+
run: pip install -e ".[local,dev]"
|
|
25
|
+
|
|
26
|
+
- name: Run tests
|
|
27
|
+
run: pytest -v --tb=short
|
|
28
|
+
|
|
29
|
+
- name: Build package
|
|
30
|
+
run: python -m build
|
|
31
|
+
|
|
32
|
+
- name: Publish to PyPI
|
|
33
|
+
env:
|
|
34
|
+
TWINE_USERNAME: __token__
|
|
35
|
+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
|
|
36
|
+
run: twine upload dist/*
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aryan
|
|
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,260 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: eviloomemvault
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Open Source memory infrastructure for AI agents
|
|
5
|
+
Author: Aryan
|
|
6
|
+
License: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Requires-Dist: fastapi>=0.110
|
|
10
|
+
Requires-Dist: pydantic>=2.0
|
|
11
|
+
Requires-Dist: structlog>=24.0
|
|
12
|
+
Requires-Dist: uvicorn>=0.29
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: mypy; extra == 'dev'
|
|
15
|
+
Requires-Dist: pre-commit; extra == 'dev'
|
|
16
|
+
Requires-Dist: pytest-cov; extra == 'dev'
|
|
17
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
18
|
+
Requires-Dist: ruff; extra == 'dev'
|
|
19
|
+
Provides-Extra: local
|
|
20
|
+
Requires-Dist: sentence-transformers>=3.0; extra == 'local'
|
|
21
|
+
Provides-Extra: postgres
|
|
22
|
+
Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
# MemVault
|
|
26
|
+
|
|
27
|
+
> Open-source memory infrastructure for AI agents.
|
|
28
|
+
|
|
29
|
+
[](https://github.com/Aryaneviloo/memvault/actions)
|
|
30
|
+
[](https://www.python.org)
|
|
31
|
+
[](LICENSE)
|
|
32
|
+
|
|
33
|
+
Most AI applications are stateless — they forget users, forget context, and treat every conversation as if it's the first. MemVault solves this by providing a production-grade memory layer that AI agents can plug into.
|
|
34
|
+
|
|
35
|
+
## What it does
|
|
36
|
+
|
|
37
|
+
- **Stores memories** with rich metadata (type, importance, confidence, tags)
|
|
38
|
+
- **Retrieves semantically** — finds relevant memories by meaning, not keyword matching
|
|
39
|
+
- **Ranks intelligently** — combines embedding similarity with recency, importance, and frequency signals
|
|
40
|
+
- **Consolidates automatically** — detects near-duplicate memories and merges them
|
|
41
|
+
- **Decays over time** — unaccessed memories fade; accessed memories are reinforced
|
|
42
|
+
- **Isolates by namespace** — per-user, per-agent, per-project memory pools
|
|
43
|
+
|
|
44
|
+
## Architecture
|
|
45
|
+
┌─────────────────────────────────────┐
|
|
46
|
+
│ Service Layer │
|
|
47
|
+
│ REST API (FastAPI) · CLI (Typer) │
|
|
48
|
+
└─────────────────┬───────────────────┘
|
|
49
|
+
│
|
|
50
|
+
┌─────────────────▼───────────────────┐
|
|
51
|
+
│ Intelligence Layer │
|
|
52
|
+
│ Hybrid Retrieval · Scoring · Decay │
|
|
53
|
+
│ Consolidation · Reinforcement │
|
|
54
|
+
└──────────┬──────────────┬───────────┘
|
|
55
|
+
│ │
|
|
56
|
+
┌──────────▼──────┐ ┌─────▼──────────┐
|
|
57
|
+
│ Storage Layer │ │ Embedding Layer │
|
|
58
|
+
│ SQLite/Postgres│ │ BGE-small (local│
|
|
59
|
+
│ In-Memory │ │ or bring your │
|
|
60
|
+
│ (adapter-based)│ │ own embedder) │
|
|
61
|
+
└─────────────────┘ └────────────────┘
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
## Quick start
|
|
65
|
+
|
|
66
|
+
### As a library
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pip install memvault
|
|
70
|
+
pip install memvault[local] # for local BGE embeddings
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
from memvault.core.models import MemoryItem, MemoryQuery, MemoryType
|
|
75
|
+
from memvault.core.retrieval import retrieve
|
|
76
|
+
from memvault.embeddings.local import LocalEmbedder
|
|
77
|
+
from memvault.storage.sqlite import SQLiteStorage
|
|
78
|
+
from memvault.storage.base import EmbeddingStorageWrapper
|
|
79
|
+
|
|
80
|
+
# Set up the stack
|
|
81
|
+
backend = SQLiteStorage("memories.db")
|
|
82
|
+
embedder = LocalEmbedder()
|
|
83
|
+
store = EmbeddingStorageWrapper(backend=backend, embedder=embedder)
|
|
84
|
+
|
|
85
|
+
# Store a memory
|
|
86
|
+
item = MemoryItem(
|
|
87
|
+
agent_id="my-agent",
|
|
88
|
+
user_id="user-123",
|
|
89
|
+
type=MemoryType.SEMANTIC,
|
|
90
|
+
content="User prefers Python over JavaScript",
|
|
91
|
+
importance=0.8,
|
|
92
|
+
)
|
|
93
|
+
store.insert(item)
|
|
94
|
+
|
|
95
|
+
# Retrieve semantically
|
|
96
|
+
query = MemoryQuery(text="programming language preferences", user_id="user-123")
|
|
97
|
+
results = retrieve(query=query, backend=backend, embedder=embedder)
|
|
98
|
+
|
|
99
|
+
for r in results:
|
|
100
|
+
print(f"[{r.final_score:.3f}] {r.item.content}")
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### As a REST API
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
# With Docker (recommended)
|
|
107
|
+
docker compose -f docker/docker-compose.yml up
|
|
108
|
+
|
|
109
|
+
# Or directly
|
|
110
|
+
uvicorn memvault.api.app:app --reload --port 8000
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# Store a memory
|
|
115
|
+
curl -X POST http://localhost:8000/memories \
|
|
116
|
+
-H "Content-Type: application/json" \
|
|
117
|
+
-d '{
|
|
118
|
+
"agent_id": "my-agent",
|
|
119
|
+
"user_id": "user-123",
|
|
120
|
+
"content": "User prefers Python over JavaScript",
|
|
121
|
+
"type": "semantic",
|
|
122
|
+
"importance": 0.8
|
|
123
|
+
}'
|
|
124
|
+
|
|
125
|
+
# Search semantically
|
|
126
|
+
curl -X POST http://localhost:8000/memories/search \
|
|
127
|
+
-H "Content-Type: application/json" \
|
|
128
|
+
-d '{
|
|
129
|
+
"text": "programming language preferences",
|
|
130
|
+
"user_id": "user-123"
|
|
131
|
+
}'
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
API docs available at `http://localhost:8000/docs`.
|
|
135
|
+
|
|
136
|
+
### As a CLI
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
memvault remember "User prefers dark mode" --user aryan
|
|
140
|
+
memvault recall "display preferences" --user aryan
|
|
141
|
+
memvault consolidate --user aryan
|
|
142
|
+
memvault doctor
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Installation
|
|
146
|
+
|
|
147
|
+
### Requirements
|
|
148
|
+
|
|
149
|
+
- Python 3.10+
|
|
150
|
+
- Docker (optional, for containerized deployment)
|
|
151
|
+
|
|
152
|
+
### Local development
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
git clone https://github.com/Aryaneviloo/memvault.git
|
|
156
|
+
cd memvault
|
|
157
|
+
|
|
158
|
+
python -m venv venv
|
|
159
|
+
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
160
|
+
|
|
161
|
+
pip install -e ".[local,dev]"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Environment variables
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
cp .env.example .env
|
|
168
|
+
# Edit .env with your values
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Running tests
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
# Core test suite (no external dependencies)
|
|
175
|
+
pytest
|
|
176
|
+
|
|
177
|
+
# With PostgreSQL backend
|
|
178
|
+
docker compose -f docker/docker-compose.yml up postgres -d
|
|
179
|
+
TEST_POSTGRES_DSN="postgresql://memvault:memvault@localhost:5433/memvault" pytest
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Memory types
|
|
183
|
+
|
|
184
|
+
| Type | Description | Example |
|
|
185
|
+
|------|-------------|---------|
|
|
186
|
+
| `episodic` | Concrete events and interactions | "User asked about Python on Jan 1" |
|
|
187
|
+
| `semantic` | Stable facts and preferences | "User prefers Python over JavaScript" |
|
|
188
|
+
| `procedural` | Useful workflows and patterns | "Run tests before committing" |
|
|
189
|
+
| `working` | Short-term session context | "Current task: debugging auth module" |
|
|
190
|
+
| `consolidated` | Summaries merged from repeated episodes | Auto-generated by consolidation |
|
|
191
|
+
|
|
192
|
+
## Storage backends
|
|
193
|
+
|
|
194
|
+
| Backend | Use case | Setup |
|
|
195
|
+
|---------|----------|-------|
|
|
196
|
+
| `InMemoryStorage` | Tests, experimentation | Zero setup |
|
|
197
|
+
| `SQLiteStorage` | Local dev, single-process production | Zero setup |
|
|
198
|
+
| `PostgresStorage` | Production, multi-process | Postgres instance required |
|
|
199
|
+
|
|
200
|
+
All backends implement the same interface — swap them with one line of code.
|
|
201
|
+
|
|
202
|
+
## Retrieval scoring
|
|
203
|
+
|
|
204
|
+
Each retrieved memory is scored by:
|
|
205
|
+
final_score = (similarity_weight × cosine_similarity)
|
|
206
|
+
+ (relevance_weight × relevance_score)
|
|
207
|
+
relevance_score = (0.4 × recency) + (0.4 × importance) + (0.2 × frequency)
|
|
208
|
+
|
|
209
|
+
All weights are configurable via `RetrievalConfig` and `ScoringWeights`.
|
|
210
|
+
|
|
211
|
+
## Project structure
|
|
212
|
+
src/memvault/
|
|
213
|
+
├── core/
|
|
214
|
+
│ ├── models.py # MemoryItem, MemoryQuery, MemoryType
|
|
215
|
+
│ ├── scoring.py # Relevance scoring, decay, reinforcement
|
|
216
|
+
│ ├── retrieval.py # Hybrid retrieval pipeline
|
|
217
|
+
│ └── consolidation.py # Near-duplicate detection and merging
|
|
218
|
+
├── storage/
|
|
219
|
+
│ ├── base.py # StorageBackend ABC + EmbeddingStorageWrapper
|
|
220
|
+
│ ├── memory.py # In-memory backend (tests/dev)
|
|
221
|
+
│ ├── sqlite.py # SQLite backend
|
|
222
|
+
│ └── postgres.py # PostgreSQL backend
|
|
223
|
+
├── embeddings/
|
|
224
|
+
│ ├── base.py # BaseEmbedder ABC
|
|
225
|
+
│ ├── local.py # BGE-small via sentence-transformers
|
|
226
|
+
│ └── provider.py # Embedder factory
|
|
227
|
+
├── api/
|
|
228
|
+
│ ├── app.py # FastAPI application factory
|
|
229
|
+
│ ├── routes.py # API endpoints
|
|
230
|
+
│ ├── schemas.py # Request/response models
|
|
231
|
+
│ └── dependencies.py # Dependency injection
|
|
232
|
+
├── cli/
|
|
233
|
+
│ └── main.py # Typer CLI
|
|
234
|
+
└── observability/
|
|
235
|
+
├── logging.py # Structured logging (structlog)
|
|
236
|
+
└── metrics.py # In-process metrics
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
## Roadmap
|
|
240
|
+
|
|
241
|
+
- [x] Core memory engine (storage, scoring, retrieval, consolidation)
|
|
242
|
+
- [x] SQLite and PostgreSQL backends
|
|
243
|
+
- [x] Local BGE embeddings
|
|
244
|
+
- [x] REST API (FastAPI)
|
|
245
|
+
- [x] CLI (Typer)
|
|
246
|
+
- [x] Docker support
|
|
247
|
+
- [ ] `MemVault` facade class (simple single-import API)
|
|
248
|
+
- [ ] LLM-based re-ranking
|
|
249
|
+
- [ ] Auto-ingest from conversation turns
|
|
250
|
+
- [ ] OpenAI / Cohere embedding providers
|
|
251
|
+
- [ ] pgvector support for native vector search
|
|
252
|
+
- [ ] Web dashboard
|
|
253
|
+
|
|
254
|
+
## Contributing
|
|
255
|
+
|
|
256
|
+
See [CONTRIBUTING.md](docs/contributing.md).
|
|
257
|
+
|
|
258
|
+
## License
|
|
259
|
+
|
|
260
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
# MemVault
|
|
2
|
+
|
|
3
|
+
> Open-source memory infrastructure for AI agents.
|
|
4
|
+
|
|
5
|
+
[](https://github.com/Aryaneviloo/memvault/actions)
|
|
6
|
+
[](https://www.python.org)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
9
|
+
Most AI applications are stateless — they forget users, forget context, and treat every conversation as if it's the first. MemVault solves this by providing a production-grade memory layer that AI agents can plug into.
|
|
10
|
+
|
|
11
|
+
## What it does
|
|
12
|
+
|
|
13
|
+
- **Stores memories** with rich metadata (type, importance, confidence, tags)
|
|
14
|
+
- **Retrieves semantically** — finds relevant memories by meaning, not keyword matching
|
|
15
|
+
- **Ranks intelligently** — combines embedding similarity with recency, importance, and frequency signals
|
|
16
|
+
- **Consolidates automatically** — detects near-duplicate memories and merges them
|
|
17
|
+
- **Decays over time** — unaccessed memories fade; accessed memories are reinforced
|
|
18
|
+
- **Isolates by namespace** — per-user, per-agent, per-project memory pools
|
|
19
|
+
|
|
20
|
+
## Architecture
|
|
21
|
+
┌─────────────────────────────────────┐
|
|
22
|
+
│ Service Layer │
|
|
23
|
+
│ REST API (FastAPI) · CLI (Typer) │
|
|
24
|
+
└─────────────────┬───────────────────┘
|
|
25
|
+
│
|
|
26
|
+
┌─────────────────▼───────────────────┐
|
|
27
|
+
│ Intelligence Layer │
|
|
28
|
+
│ Hybrid Retrieval · Scoring · Decay │
|
|
29
|
+
│ Consolidation · Reinforcement │
|
|
30
|
+
└──────────┬──────────────┬───────────┘
|
|
31
|
+
│ │
|
|
32
|
+
┌──────────▼──────┐ ┌─────▼──────────┐
|
|
33
|
+
│ Storage Layer │ │ Embedding Layer │
|
|
34
|
+
│ SQLite/Postgres│ │ BGE-small (local│
|
|
35
|
+
│ In-Memory │ │ or bring your │
|
|
36
|
+
│ (adapter-based)│ │ own embedder) │
|
|
37
|
+
└─────────────────┘ └────────────────┘
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
## Quick start
|
|
41
|
+
|
|
42
|
+
### As a library
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install memvault
|
|
46
|
+
pip install memvault[local] # for local BGE embeddings
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
from memvault.core.models import MemoryItem, MemoryQuery, MemoryType
|
|
51
|
+
from memvault.core.retrieval import retrieve
|
|
52
|
+
from memvault.embeddings.local import LocalEmbedder
|
|
53
|
+
from memvault.storage.sqlite import SQLiteStorage
|
|
54
|
+
from memvault.storage.base import EmbeddingStorageWrapper
|
|
55
|
+
|
|
56
|
+
# Set up the stack
|
|
57
|
+
backend = SQLiteStorage("memories.db")
|
|
58
|
+
embedder = LocalEmbedder()
|
|
59
|
+
store = EmbeddingStorageWrapper(backend=backend, embedder=embedder)
|
|
60
|
+
|
|
61
|
+
# Store a memory
|
|
62
|
+
item = MemoryItem(
|
|
63
|
+
agent_id="my-agent",
|
|
64
|
+
user_id="user-123",
|
|
65
|
+
type=MemoryType.SEMANTIC,
|
|
66
|
+
content="User prefers Python over JavaScript",
|
|
67
|
+
importance=0.8,
|
|
68
|
+
)
|
|
69
|
+
store.insert(item)
|
|
70
|
+
|
|
71
|
+
# Retrieve semantically
|
|
72
|
+
query = MemoryQuery(text="programming language preferences", user_id="user-123")
|
|
73
|
+
results = retrieve(query=query, backend=backend, embedder=embedder)
|
|
74
|
+
|
|
75
|
+
for r in results:
|
|
76
|
+
print(f"[{r.final_score:.3f}] {r.item.content}")
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### As a REST API
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
# With Docker (recommended)
|
|
83
|
+
docker compose -f docker/docker-compose.yml up
|
|
84
|
+
|
|
85
|
+
# Or directly
|
|
86
|
+
uvicorn memvault.api.app:app --reload --port 8000
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
# Store a memory
|
|
91
|
+
curl -X POST http://localhost:8000/memories \
|
|
92
|
+
-H "Content-Type: application/json" \
|
|
93
|
+
-d '{
|
|
94
|
+
"agent_id": "my-agent",
|
|
95
|
+
"user_id": "user-123",
|
|
96
|
+
"content": "User prefers Python over JavaScript",
|
|
97
|
+
"type": "semantic",
|
|
98
|
+
"importance": 0.8
|
|
99
|
+
}'
|
|
100
|
+
|
|
101
|
+
# Search semantically
|
|
102
|
+
curl -X POST http://localhost:8000/memories/search \
|
|
103
|
+
-H "Content-Type: application/json" \
|
|
104
|
+
-d '{
|
|
105
|
+
"text": "programming language preferences",
|
|
106
|
+
"user_id": "user-123"
|
|
107
|
+
}'
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
API docs available at `http://localhost:8000/docs`.
|
|
111
|
+
|
|
112
|
+
### As a CLI
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
memvault remember "User prefers dark mode" --user aryan
|
|
116
|
+
memvault recall "display preferences" --user aryan
|
|
117
|
+
memvault consolidate --user aryan
|
|
118
|
+
memvault doctor
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Installation
|
|
122
|
+
|
|
123
|
+
### Requirements
|
|
124
|
+
|
|
125
|
+
- Python 3.10+
|
|
126
|
+
- Docker (optional, for containerized deployment)
|
|
127
|
+
|
|
128
|
+
### Local development
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
git clone https://github.com/Aryaneviloo/memvault.git
|
|
132
|
+
cd memvault
|
|
133
|
+
|
|
134
|
+
python -m venv venv
|
|
135
|
+
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
136
|
+
|
|
137
|
+
pip install -e ".[local,dev]"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Environment variables
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
cp .env.example .env
|
|
144
|
+
# Edit .env with your values
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Running tests
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
# Core test suite (no external dependencies)
|
|
151
|
+
pytest
|
|
152
|
+
|
|
153
|
+
# With PostgreSQL backend
|
|
154
|
+
docker compose -f docker/docker-compose.yml up postgres -d
|
|
155
|
+
TEST_POSTGRES_DSN="postgresql://memvault:memvault@localhost:5433/memvault" pytest
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Memory types
|
|
159
|
+
|
|
160
|
+
| Type | Description | Example |
|
|
161
|
+
|------|-------------|---------|
|
|
162
|
+
| `episodic` | Concrete events and interactions | "User asked about Python on Jan 1" |
|
|
163
|
+
| `semantic` | Stable facts and preferences | "User prefers Python over JavaScript" |
|
|
164
|
+
| `procedural` | Useful workflows and patterns | "Run tests before committing" |
|
|
165
|
+
| `working` | Short-term session context | "Current task: debugging auth module" |
|
|
166
|
+
| `consolidated` | Summaries merged from repeated episodes | Auto-generated by consolidation |
|
|
167
|
+
|
|
168
|
+
## Storage backends
|
|
169
|
+
|
|
170
|
+
| Backend | Use case | Setup |
|
|
171
|
+
|---------|----------|-------|
|
|
172
|
+
| `InMemoryStorage` | Tests, experimentation | Zero setup |
|
|
173
|
+
| `SQLiteStorage` | Local dev, single-process production | Zero setup |
|
|
174
|
+
| `PostgresStorage` | Production, multi-process | Postgres instance required |
|
|
175
|
+
|
|
176
|
+
All backends implement the same interface — swap them with one line of code.
|
|
177
|
+
|
|
178
|
+
## Retrieval scoring
|
|
179
|
+
|
|
180
|
+
Each retrieved memory is scored by:
|
|
181
|
+
final_score = (similarity_weight × cosine_similarity)
|
|
182
|
+
+ (relevance_weight × relevance_score)
|
|
183
|
+
relevance_score = (0.4 × recency) + (0.4 × importance) + (0.2 × frequency)
|
|
184
|
+
|
|
185
|
+
All weights are configurable via `RetrievalConfig` and `ScoringWeights`.
|
|
186
|
+
|
|
187
|
+
## Project structure
|
|
188
|
+
src/memvault/
|
|
189
|
+
├── core/
|
|
190
|
+
│ ├── models.py # MemoryItem, MemoryQuery, MemoryType
|
|
191
|
+
│ ├── scoring.py # Relevance scoring, decay, reinforcement
|
|
192
|
+
│ ├── retrieval.py # Hybrid retrieval pipeline
|
|
193
|
+
│ └── consolidation.py # Near-duplicate detection and merging
|
|
194
|
+
├── storage/
|
|
195
|
+
│ ├── base.py # StorageBackend ABC + EmbeddingStorageWrapper
|
|
196
|
+
│ ├── memory.py # In-memory backend (tests/dev)
|
|
197
|
+
│ ├── sqlite.py # SQLite backend
|
|
198
|
+
│ └── postgres.py # PostgreSQL backend
|
|
199
|
+
├── embeddings/
|
|
200
|
+
│ ├── base.py # BaseEmbedder ABC
|
|
201
|
+
│ ├── local.py # BGE-small via sentence-transformers
|
|
202
|
+
│ └── provider.py # Embedder factory
|
|
203
|
+
├── api/
|
|
204
|
+
│ ├── app.py # FastAPI application factory
|
|
205
|
+
│ ├── routes.py # API endpoints
|
|
206
|
+
│ ├── schemas.py # Request/response models
|
|
207
|
+
│ └── dependencies.py # Dependency injection
|
|
208
|
+
├── cli/
|
|
209
|
+
│ └── main.py # Typer CLI
|
|
210
|
+
└── observability/
|
|
211
|
+
├── logging.py # Structured logging (structlog)
|
|
212
|
+
└── metrics.py # In-process metrics
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
## Roadmap
|
|
216
|
+
|
|
217
|
+
- [x] Core memory engine (storage, scoring, retrieval, consolidation)
|
|
218
|
+
- [x] SQLite and PostgreSQL backends
|
|
219
|
+
- [x] Local BGE embeddings
|
|
220
|
+
- [x] REST API (FastAPI)
|
|
221
|
+
- [x] CLI (Typer)
|
|
222
|
+
- [x] Docker support
|
|
223
|
+
- [ ] `MemVault` facade class (simple single-import API)
|
|
224
|
+
- [ ] LLM-based re-ranking
|
|
225
|
+
- [ ] Auto-ingest from conversation turns
|
|
226
|
+
- [ ] OpenAI / Cohere embedding providers
|
|
227
|
+
- [ ] pgvector support for native vector search
|
|
228
|
+
- [ ] Web dashboard
|
|
229
|
+
|
|
230
|
+
## Contributing
|
|
231
|
+
|
|
232
|
+
See [CONTRIBUTING.md](docs/contributing.md).
|
|
233
|
+
|
|
234
|
+
## License
|
|
235
|
+
|
|
236
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
version: "3.9"
|
|
2
|
+
|
|
3
|
+
services:
|
|
4
|
+
api:
|
|
5
|
+
build:
|
|
6
|
+
context: ..
|
|
7
|
+
dockerfile: docker/dockerfile
|
|
8
|
+
ports:
|
|
9
|
+
- "8000:8000"
|
|
10
|
+
volumes:
|
|
11
|
+
- memories_data:/app/data
|
|
12
|
+
environment:
|
|
13
|
+
- LOG_LEVEL=INFO
|
|
14
|
+
- HF_HUB_OFFLINE=1
|
|
15
|
+
- DB_PATH=/app/data/memories.db
|
|
16
|
+
depends_on:
|
|
17
|
+
postgres:
|
|
18
|
+
condition: service_healthy
|
|
19
|
+
healthcheck:
|
|
20
|
+
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
|
|
21
|
+
interval: 30s
|
|
22
|
+
timeout: 10s
|
|
23
|
+
retries: 3
|
|
24
|
+
start_period: 40s
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
postgres:
|
|
28
|
+
image: postgres:16-alpine
|
|
29
|
+
environment:
|
|
30
|
+
POSTGRES_USER: memvault
|
|
31
|
+
POSTGRES_PASSWORD: memvault
|
|
32
|
+
POSTGRES_DB: memvault
|
|
33
|
+
ports:
|
|
34
|
+
- "5433:5432"
|
|
35
|
+
volumes:
|
|
36
|
+
- postgres_data:/var/lib/postgresq1/data
|
|
37
|
+
healthcheck:
|
|
38
|
+
test: ["CMD-SHELL", "pg_isready -U memvault"]
|
|
39
|
+
interval: 5s
|
|
40
|
+
timeout: 5s
|
|
41
|
+
retries: 5
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
volumes:
|
|
45
|
+
memories_data:
|
|
46
|
+
postgres_data:
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
FROM python:3.10-slim
|
|
2
|
+
|
|
3
|
+
WORKDIR /app
|
|
4
|
+
|
|
5
|
+
RUN apt-get update && apt-get install -y\
|
|
6
|
+
build-essential \
|
|
7
|
+
curl \
|
|
8
|
+
&& rm -rf /var/lib/apt/lists/*
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
COPY pyproject.toml .
|
|
12
|
+
COPY README.md .
|
|
13
|
+
|
|
14
|
+
COPY src/ src/
|
|
15
|
+
|
|
16
|
+
RUN pip install --no-cache-dir -e ".[local]"
|
|
17
|
+
|
|
18
|
+
RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-en-v1.5')"
|
|
19
|
+
|
|
20
|
+
EXPOSE 8000
|
|
21
|
+
|
|
22
|
+
# Environment variables
|
|
23
|
+
ENV PYTHONUNBUFFERED=1
|
|
24
|
+
ENV HF_HUB_OFFLINE=1
|
|
25
|
+
ENV LOG_LEVEL=INFO
|
|
26
|
+
|
|
27
|
+
# Command to run when container starts
|
|
28
|
+
CMD ["uvicorn", "memorycore.api.app:app", "--host", "0.0.0.0", "--port", "8000"]
|