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.
Files changed (50) hide show
  1. eviloomemvault-0.1.0/.dockerignore +9 -0
  2. eviloomemvault-0.1.0/.env.example +15 -0
  3. eviloomemvault-0.1.0/.github/workflows/ci.yml +28 -0
  4. eviloomemvault-0.1.0/.github/workflows/release.yaml +36 -0
  5. eviloomemvault-0.1.0/.gitignore +12 -0
  6. eviloomemvault-0.1.0/LICENSE +21 -0
  7. eviloomemvault-0.1.0/PKG-INFO +260 -0
  8. eviloomemvault-0.1.0/README.md +236 -0
  9. eviloomemvault-0.1.0/docker/docker-compose.yml +46 -0
  10. eviloomemvault-0.1.0/docker/dockerfile +28 -0
  11. eviloomemvault-0.1.0/docs/architecture.md +101 -0
  12. eviloomemvault-0.1.0/docs/contributing.md +51 -0
  13. eviloomemvault-0.1.0/docs/getting-started.md +253 -0
  14. eviloomemvault-0.1.0/examples/agent_integration.py +117 -0
  15. eviloomemvault-0.1.0/examples/basic_usage.py +91 -0
  16. eviloomemvault-0.1.0/pyproject.toml +60 -0
  17. eviloomemvault-0.1.0/src/memvault/__init__.py +26 -0
  18. eviloomemvault-0.1.0/src/memvault/api/__init__.py +0 -0
  19. eviloomemvault-0.1.0/src/memvault/api/app.py +59 -0
  20. eviloomemvault-0.1.0/src/memvault/api/dependencies.py +28 -0
  21. eviloomemvault-0.1.0/src/memvault/api/routes.py +207 -0
  22. eviloomemvault-0.1.0/src/memvault/api/schemas.py +98 -0
  23. eviloomemvault-0.1.0/src/memvault/cli/__init__.py +0 -0
  24. eviloomemvault-0.1.0/src/memvault/cli/main.py +193 -0
  25. eviloomemvault-0.1.0/src/memvault/core/__init__.py +0 -0
  26. eviloomemvault-0.1.0/src/memvault/core/consolidation.py +166 -0
  27. eviloomemvault-0.1.0/src/memvault/core/models.py +66 -0
  28. eviloomemvault-0.1.0/src/memvault/core/retrieval.py +126 -0
  29. eviloomemvault-0.1.0/src/memvault/core/scoring.py +135 -0
  30. eviloomemvault-0.1.0/src/memvault/embeddings/__init__.py +0 -0
  31. eviloomemvault-0.1.0/src/memvault/embeddings/base.py +34 -0
  32. eviloomemvault-0.1.0/src/memvault/embeddings/local.py +48 -0
  33. eviloomemvault-0.1.0/src/memvault/embeddings/provider.py +18 -0
  34. eviloomemvault-0.1.0/src/memvault/memvault.py +260 -0
  35. eviloomemvault-0.1.0/src/memvault/observability/__init__.py +0 -0
  36. eviloomemvault-0.1.0/src/memvault/observability/logging.py +46 -0
  37. eviloomemvault-0.1.0/src/memvault/observability/metrics.py +56 -0
  38. eviloomemvault-0.1.0/src/memvault/storage/__init__.py +0 -0
  39. eviloomemvault-0.1.0/src/memvault/storage/base.py +107 -0
  40. eviloomemvault-0.1.0/src/memvault/storage/memory.py +70 -0
  41. eviloomemvault-0.1.0/src/memvault/storage/postgres.py +216 -0
  42. eviloomemvault-0.1.0/src/memvault/storage/sqlite.py +187 -0
  43. eviloomemvault-0.1.0/tests/test_api.py +181 -0
  44. eviloomemvault-0.1.0/tests/test_consolidation.py +158 -0
  45. eviloomemvault-0.1.0/tests/test_decay_reinforcement.py +92 -0
  46. eviloomemvault-0.1.0/tests/test_embeddings.py +72 -0
  47. eviloomemvault-0.1.0/tests/test_models.py +67 -0
  48. eviloomemvault-0.1.0/tests/test_retrieval.py +134 -0
  49. eviloomemvault-0.1.0/tests/test_scoring.py +95 -0
  50. eviloomemvault-0.1.0/tests/test_storage_contract.py +221 -0
@@ -0,0 +1,9 @@
1
+ venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .git/
5
+ .pytest_cache/
6
+ *.db
7
+ .env
8
+ htmlcov/
9
+ .coverage
@@ -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,12 @@
1
+ __pycache__/
2
+ venv/
3
+ *.pyc
4
+ .pytest_cache/
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ *.egg-info/
8
+ .env
9
+ *.db
10
+ .coverage
11
+ htmlcov/
12
+ 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
+ [![Tests](https://github.com/Aryaneviloo/memvault/actions/workflows/ci.yml/badge.svg)](https://github.com/Aryaneviloo/memvault/actions)
30
+ [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
31
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
+ [![Tests](https://github.com/Aryaneviloo/memvault/actions/workflows/ci.yml/badge.svg)](https://github.com/Aryaneviloo/memvault/actions)
6
+ [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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"]