memboot 0.2.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 (58) hide show
  1. memboot-0.2.0/.github/dependabot.yml +13 -0
  2. memboot-0.2.0/.github/workflows/ci.yml +42 -0
  3. memboot-0.2.0/.github/workflows/codeql.yml +33 -0
  4. memboot-0.2.0/.github/workflows/release.yml +41 -0
  5. memboot-0.2.0/.github/workflows/secret-scan.yml +26 -0
  6. memboot-0.2.0/.github/workflows/security.yml +25 -0
  7. memboot-0.2.0/.gitignore +18 -0
  8. memboot-0.2.0/.gitleaks.toml +11 -0
  9. memboot-0.2.0/CLAUDE.md +99 -0
  10. memboot-0.2.0/LICENSE +21 -0
  11. memboot-0.2.0/PKG-INFO +154 -0
  12. memboot-0.2.0/README.md +108 -0
  13. memboot-0.2.0/pyproject.toml +75 -0
  14. memboot-0.2.0/setup.cfg +4 -0
  15. memboot-0.2.0/src/memboot/__init__.py +4 -0
  16. memboot-0.2.0/src/memboot/__main__.py +8 -0
  17. memboot-0.2.0/src/memboot/chunker.py +314 -0
  18. memboot-0.2.0/src/memboot/cli.py +319 -0
  19. memboot-0.2.0/src/memboot/context.py +45 -0
  20. memboot-0.2.0/src/memboot/embedder.py +161 -0
  21. memboot-0.2.0/src/memboot/exceptions.py +35 -0
  22. memboot-0.2.0/src/memboot/gates.py +31 -0
  23. memboot-0.2.0/src/memboot/indexer.py +241 -0
  24. memboot-0.2.0/src/memboot/ingest/__init__.py +3 -0
  25. memboot-0.2.0/src/memboot/ingest/files.py +73 -0
  26. memboot-0.2.0/src/memboot/ingest/pdf.py +95 -0
  27. memboot-0.2.0/src/memboot/ingest/web.py +90 -0
  28. memboot-0.2.0/src/memboot/licensing.py +182 -0
  29. memboot-0.2.0/src/memboot/mcp_server.py +124 -0
  30. memboot-0.2.0/src/memboot/memory.py +77 -0
  31. memboot-0.2.0/src/memboot/models.py +128 -0
  32. memboot-0.2.0/src/memboot/query.py +98 -0
  33. memboot-0.2.0/src/memboot/store.py +325 -0
  34. memboot-0.2.0/src/memboot/watcher.py +104 -0
  35. memboot-0.2.0/src/memboot.egg-info/PKG-INFO +154 -0
  36. memboot-0.2.0/src/memboot.egg-info/SOURCES.txt +56 -0
  37. memboot-0.2.0/src/memboot.egg-info/dependency_links.txt +1 -0
  38. memboot-0.2.0/src/memboot.egg-info/entry_points.txt +2 -0
  39. memboot-0.2.0/src/memboot.egg-info/requires.txt +27 -0
  40. memboot-0.2.0/src/memboot.egg-info/top_level.txt +1 -0
  41. memboot-0.2.0/tests/__init__.py +0 -0
  42. memboot-0.2.0/tests/conftest.py +84 -0
  43. memboot-0.2.0/tests/test_chunker.py +254 -0
  44. memboot-0.2.0/tests/test_cli.py +314 -0
  45. memboot-0.2.0/tests/test_context.py +90 -0
  46. memboot-0.2.0/tests/test_embedder.py +139 -0
  47. memboot-0.2.0/tests/test_exceptions.py +45 -0
  48. memboot-0.2.0/tests/test_gates.py +43 -0
  49. memboot-0.2.0/tests/test_indexer.py +315 -0
  50. memboot-0.2.0/tests/test_ingest.py +236 -0
  51. memboot-0.2.0/tests/test_licensing.py +216 -0
  52. memboot-0.2.0/tests/test_main_module.py +13 -0
  53. memboot-0.2.0/tests/test_mcp_server.py +217 -0
  54. memboot-0.2.0/tests/test_memory.py +118 -0
  55. memboot-0.2.0/tests/test_models.py +185 -0
  56. memboot-0.2.0/tests/test_query.py +198 -0
  57. memboot-0.2.0/tests/test_store.py +288 -0
  58. memboot-0.2.0/tests/test_watcher.py +167 -0
@@ -0,0 +1,13 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: pip
4
+ directory: "/"
5
+ schedule:
6
+ interval: weekly
7
+ ignore:
8
+ - dependency-name: "*"
9
+ update-types: ["version-update:semver-major"]
10
+ - package-ecosystem: github-actions
11
+ directory: "/"
12
+ schedule:
13
+ interval: weekly
@@ -0,0 +1,42 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ lint:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - uses: actions/setup-python@v6
15
+ with:
16
+ python-version: "3.12"
17
+ - run: pip install ruff
18
+ - run: ruff check src/ tests/
19
+ - run: ruff format --check src/ tests/
20
+
21
+ test:
22
+ runs-on: ubuntu-latest
23
+ strategy:
24
+ matrix:
25
+ python-version: ["3.11", "3.12", "3.13"]
26
+ steps:
27
+ - uses: actions/checkout@v4
28
+ - uses: actions/setup-python@v6
29
+ with:
30
+ python-version: ${{ matrix.python-version }}
31
+ - run: pip install -e ".[dev]"
32
+ - run: pytest tests/ -v
33
+
34
+ gitleaks:
35
+ runs-on: ubuntu-latest
36
+ steps:
37
+ - uses: actions/checkout@v4
38
+ with:
39
+ fetch-depth: 0
40
+ - uses: gitleaks/gitleaks-action@v2
41
+ env:
42
+ GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}
@@ -0,0 +1,33 @@
1
+ name: CodeQL Security Scan
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+ schedule:
9
+ - cron: "0 6 * * 1"
10
+
11
+ jobs:
12
+ analyze:
13
+ name: Analyze
14
+ runs-on: ubuntu-latest
15
+ permissions:
16
+ actions: read
17
+ contents: read
18
+ security-events: write
19
+
20
+ steps:
21
+ - name: Checkout repository
22
+ uses: actions/checkout@v4
23
+
24
+ - name: Initialize CodeQL
25
+ uses: github/codeql-action/init@v4
26
+ with:
27
+ languages: python
28
+ queries: security-and-quality
29
+
30
+ - name: Perform CodeQL Analysis
31
+ uses: github/codeql-action/analyze@v4
32
+ with:
33
+ category: "/language:python"
@@ -0,0 +1,41 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ permissions:
8
+ contents: write
9
+ id-token: write
10
+
11
+ jobs:
12
+ release:
13
+ runs-on: ubuntu-latest
14
+ environment: pypi
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+
18
+ - name: Set up Python
19
+ uses: actions/setup-python@v6
20
+ with:
21
+ python-version: "3.12"
22
+
23
+ - name: Install dependencies
24
+ run: pip install -e ".[dev]"
25
+
26
+ - name: Run tests
27
+ run: pytest -q --no-header --tb=short
28
+
29
+ - name: Build package
30
+ run: |
31
+ pip install build
32
+ python -m build
33
+
34
+ - name: Create GitHub Release
35
+ uses: softprops/action-gh-release@v2
36
+ with:
37
+ generate_release_notes: true
38
+ files: dist/*
39
+
40
+ - name: Publish to PyPI
41
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,26 @@
1
+ name: Secret Scan
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ gitleaks:
11
+ name: Scan for secrets
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - name: Checkout
15
+ uses: actions/checkout@v4
16
+ with:
17
+ fetch-depth: 0
18
+
19
+ - name: Install Gitleaks
20
+ run: |
21
+ curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.24.3/gitleaks_8.24.3_linux_x64.tar.gz | tar xz
22
+ chmod +x gitleaks
23
+
24
+ - name: Run Gitleaks
25
+ run: |
26
+ ./gitleaks detect --source . --verbose --redact --exit-code 2
@@ -0,0 +1,25 @@
1
+ name: Security
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+ schedule:
9
+ - cron: '0 6 * * 1'
10
+
11
+ jobs:
12
+ pip-audit:
13
+ name: Dependency Audit
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ - uses: actions/setup-python@v6
18
+ with:
19
+ python-version: "3.12"
20
+ - name: Install dependencies
21
+ run: |
22
+ pip install -e ".[dev]"
23
+ pip install pip-audit
24
+ - name: Run pip-audit
25
+ run: pip-audit
@@ -0,0 +1,18 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+ *.egg-info/
5
+ *.egg
6
+ dist/
7
+ build/
8
+ .eggs/
9
+ .venv/
10
+ venv/
11
+ .mypy_cache/
12
+ .ruff_cache/
13
+ .pytest_cache/
14
+ *.so
15
+ .coverage
16
+ htmlcov/
17
+ .env
18
+ *.log
@@ -0,0 +1,11 @@
1
+ [extend]
2
+ useDefault = true
3
+
4
+ [allowlist]
5
+ regexTarget = "match"
6
+ regexes = [
7
+ '''memboot-v1''',
8
+ ]
9
+ paths = [
10
+ '''tests/''',
11
+ ]
@@ -0,0 +1,99 @@
1
+ # memboot
2
+
3
+ Zero-infrastructure persistent memory for any LLM. SQLite + TF-IDF vector search with no external services.
4
+
5
+ ## Quick Reference
6
+
7
+ - **Version**: 0.2.0
8
+ - **Python**: >=3.11
9
+ - **Package layout**: `src/memboot/` (setuptools, `src` layout)
10
+ - **Tests**: `tests/` (pytest, 285 tests, 95% coverage, fail_under=90)
11
+ - **License**: MIT
12
+
13
+ ## Build & Run
14
+
15
+ ```bash
16
+ python3 -m venv .venv && source .venv/bin/activate
17
+ pip install -e ".[dev]"
18
+
19
+ # CLI
20
+ memboot --version
21
+ memboot init <project-path>
22
+ memboot query "search terms" --project <path>
23
+ memboot remember "important fact" --type note --project <path>
24
+ memboot context "query" --project <path>
25
+ memboot status
26
+ memboot reset --project <path> --yes
27
+ memboot ingest <file-or-url> --project <path>
28
+ memboot serve # Pro only — MCP server
29
+ ```
30
+
31
+ ## Testing
32
+
33
+ ```bash
34
+ pytest tests/ -v # Full suite with coverage
35
+ pytest tests/test_store.py -v # Single module
36
+ ```
37
+
38
+ Coverage gate: 90% (enforced in pyproject.toml via `--cov-fail-under=90`).
39
+
40
+ ## Linting
41
+
42
+ ```bash
43
+ ruff check src/ tests/ # Lint
44
+ ruff format src/ tests/ # Format (auto-fix)
45
+ ruff check src/ tests/ && ruff format --check src/ tests/ # CI check
46
+ ```
47
+
48
+ Rules: E, F, W, I, N, UP, B, A, SIM. B008 ignored for `cli.py` (typer defaults).
49
+
50
+ ## Architecture
51
+
52
+ ```
53
+ src/memboot/
54
+ ├── __init__.py # Version
55
+ ├── __main__.py # Entry point
56
+ ├── models.py # Pydantic models (Chunk, Memory, SearchResult, ProjectInfo, MembootConfig)
57
+ ├── exceptions.py # MembootError hierarchy (7 subclasses)
58
+ ├── store.py # SQLite WAL store (chunks/memories/meta, numpy BLOB serialization)
59
+ ├── embedder.py # TfidfEmbedder (numpy-only), SentenceTransformerEmbedder (optional)
60
+ ├── chunker.py # AST-based Python chunking + markdown/yaml/json/window strategies
61
+ ├── indexer.py # Full pipeline: discover → chunk → embed → store
62
+ ├── query.py # Cosine similarity search over chunks + memories
63
+ ├── memory.py # CRUD for persistent memories
64
+ ├── context.py # Formatted markdown context builder with token budget
65
+ ├── licensing.py # MMBT license keys, HMAC checksum, Free/Pro tiers
66
+ ├── gates.py # @require_pro decorator
67
+ ├── watcher.py # File system watcher (watchdog, debounced auto-reindex)
68
+ ├── mcp_server.py # MCP server (3 tools: query_memory, remember, get_context)
69
+ └── ingest/
70
+ ├── files.py # File ingestion (chunk + embed + store)
71
+ ├── pdf.py # PDF ingestion (pdfplumber, optional)
72
+ └── web.py # Web ingestion (trafilatura, optional)
73
+ ```
74
+
75
+ ## Key Patterns
76
+
77
+ - **Lazy imports**: CLI commands import at function level. Optional deps (mcp, pdfplumber, trafilatura, sentence-transformers) use try/except ImportError.
78
+ - **Patch targets**: When testing CLI, patch at source modules (`memboot.indexer.index_project`), not `memboot.cli.xxx`.
79
+ - **Store**: SQLite WAL mode, numpy float32 BLOB serialization, INSERT OR REPLACE for upserts.
80
+ - **Embeddings**: TF-IDF state saved to store meta as JSON, restored on query/ingest.
81
+ - **Licensing**: MMBT prefix, `memboot-v1` salt, SHA256 checksum. Key via `MEMBOOT_LICENSE` env var or `~/.memboot-license` file.
82
+ - **Per-project DB**: `~/.memboot/{sha256(project_path)[:12]}.db` — one DB per project, auto-created on `init`.
83
+
84
+ ## Optional Dependencies
85
+
86
+ ```bash
87
+ pip install memboot[mcp] # MCP server support
88
+ pip install memboot[pdf] # PDF ingestion (pdfplumber)
89
+ pip install memboot[web] # Web ingestion (trafilatura)
90
+ pip install memboot[embed] # Sentence-transformer embeddings
91
+ ```
92
+
93
+ ## Conventions
94
+
95
+ - Type hints throughout (mypy strict)
96
+ - `from __future__ import annotations` in test files
97
+ - Pydantic v2 models with StrEnum
98
+ - Ruff for all linting/formatting
99
+ - Conventional commits
memboot-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AreteDriver
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.
memboot-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,154 @@
1
+ Metadata-Version: 2.4
2
+ Name: memboot
3
+ Version: 0.2.0
4
+ Summary: Zero-infrastructure persistent memory for any LLM
5
+ Author: AreteDriver
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/AreteDriver/memboot
8
+ Project-URL: Repository, https://github.com/AreteDriver/memboot
9
+ Project-URL: Issues, https://github.com/AreteDriver/memboot/issues
10
+ Keywords: memory,llm,mcp,embeddings,vector-search,ai,rag
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development :: Build Tools
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: typer>=0.9.0
25
+ Requires-Dist: rich>=13.0
26
+ Requires-Dist: pydantic>=2.0
27
+ Requires-Dist: numpy>=1.24
28
+ Requires-Dist: pyyaml>=6.0
29
+ Provides-Extra: embed
30
+ Requires-Dist: sentence-transformers>=2.0; extra == "embed"
31
+ Provides-Extra: mcp
32
+ Requires-Dist: mcp>=1.0; extra == "mcp"
33
+ Provides-Extra: pdf
34
+ Requires-Dist: pdfplumber>=0.10; extra == "pdf"
35
+ Provides-Extra: watch
36
+ Requires-Dist: watchdog>=3.0; extra == "watch"
37
+ Provides-Extra: web
38
+ Requires-Dist: trafilatura>=1.6; extra == "web"
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest>=7.0; extra == "dev"
41
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
42
+ Requires-Dist: mypy>=1.0; extra == "dev"
43
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
44
+ Requires-Dist: watchdog>=3.0; extra == "dev"
45
+ Dynamic: license-file
46
+
47
+ # memboot
48
+
49
+ [![CI](https://github.com/AreteDriver/memboot/actions/workflows/ci.yml/badge.svg)](https://github.com/AreteDriver/memboot/actions/workflows/ci.yml)
50
+ [![CodeQL](https://github.com/AreteDriver/memboot/actions/workflows/codeql.yml/badge.svg)](https://github.com/AreteDriver/memboot/actions/workflows/codeql.yml)
51
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
52
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
53
+
54
+ **Zero-infrastructure persistent memory for any LLM.**
55
+
56
+ Index your codebase, store decisions, and search everything with vector similarity — all local, all SQLite, no API keys needed.
57
+
58
+ ## Features
59
+
60
+ - **Smart chunking** — AST-aware Python extraction, Markdown heading splits, YAML/JSON key-level, sliding window fallback
61
+ - **Local embeddings** — Built-in TF-IDF (zero deps), optional sentence-transformers for semantic search
62
+ - **Episodic memory** — Store decisions, patterns, observations alongside your code index
63
+ - **Context builder** — Token-budgeted markdown blocks ready for LLM prompts
64
+ - **MCP server** — Expose memory as tools for Claude Code, Cursor, and other MCP clients (Pro)
65
+ - **File ingestion** — Ingest external files, PDFs, and web pages into project memory
66
+
67
+ ## Install
68
+
69
+ ```bash
70
+ pip install memboot
71
+ ```
72
+
73
+ Optional extras:
74
+
75
+ ```bash
76
+ pip install memboot[embed] # sentence-transformers for semantic embeddings
77
+ pip install memboot[mcp] # MCP server support
78
+ pip install memboot[pdf] # PDF ingestion
79
+ pip install memboot[watch] # File watching for auto-reindex
80
+ pip install memboot[web] # Web page ingestion
81
+ ```
82
+
83
+ ## Quick Start
84
+
85
+ ```bash
86
+ # Index a project
87
+ memboot init /path/to/your/project
88
+
89
+ # Search for relevant code and memories
90
+ memboot query "authentication flow" --project /path/to/your/project
91
+
92
+ # Store a decision
93
+ memboot remember "Use JWT for API auth, sessions for web" --type decision --project /path/to/your/project
94
+
95
+ # Get formatted context for an LLM prompt
96
+ memboot context "database schema" --project /path/to/your/project --max-tokens 4000
97
+
98
+ # Check license status
99
+ memboot status
100
+ ```
101
+
102
+ ## CLI Commands
103
+
104
+ | Command | Description |
105
+ |---------|-------------|
106
+ | `memboot init` | Scan, chunk, embed, and index a project |
107
+ | `memboot query` | Search project memory by similarity |
108
+ | `memboot remember` | Store an episodic memory (decision, note, observation, pattern) |
109
+ | `memboot context` | Export a formatted context block with token budget |
110
+ | `memboot status` | Show license tier and available features |
111
+ | `memboot reset` | Clear all indexed data and memories |
112
+ | `memboot ingest` | Add external files, PDFs, or URLs to memory |
113
+ | `memboot watch` | Watch project and auto-reindex on changes |
114
+ | `memboot serve` | Start MCP stdio server (Pro) |
115
+
116
+ ## How It Works
117
+
118
+ ```
119
+ Project Files ──→ Chunker ──→ Embedder ──→ SQLite Store
120
+ (AST) (TF-IDF) (~/.memboot/)
121
+
122
+ Query Text ─────→ Embedder ──→ Cosine Sim ──→ Results
123
+
124
+ Memories ───────→ Embedder ──→ Store ───────→ Searchable
125
+ ```
126
+
127
+ 1. **Index** — Recursively discover files, chunk by language (Python AST, Markdown headers, etc.), embed with TF-IDF, store in SQLite
128
+ 2. **Query** — Embed your query, compute cosine similarity against all chunks and memories, return top-K
129
+ 3. **Remember** — Store episodic memories (decisions, patterns, observations) with embeddings for later retrieval
130
+ 4. **Context** — Build token-budgeted markdown blocks with source attribution for LLM consumption
131
+
132
+ Each project gets its own SQLite database at `~/.memboot/{hash}.db`. No servers, no API keys, no network calls.
133
+
134
+ ## Architecture
135
+
136
+ ```
137
+ src/memboot/
138
+ ├── models.py # Pydantic v2 data models
139
+ ├── store.py # SQLite WAL backend (numpy BLOB serialization)
140
+ ├── chunker.py # Language-aware chunking (Python/MD/YAML/JSON/window)
141
+ ├── embedder.py # TF-IDF (built-in) + sentence-transformers (optional)
142
+ ├── indexer.py # Discovery → chunk → embed → store pipeline
143
+ ├── query.py # Cosine similarity search
144
+ ├── memory.py # Episodic memory CRUD
145
+ ├── context.py # Token-budgeted context builder
146
+ ├── licensing.py # Free/Pro tier management
147
+ ├── cli.py # 8 Typer CLI commands
148
+ ├── mcp_server.py # MCP stdio server (3 tools)
149
+ └── ingest/ # External file/PDF/web ingestion
150
+ ```
151
+
152
+ ## License
153
+
154
+ MIT
@@ -0,0 +1,108 @@
1
+ # memboot
2
+
3
+ [![CI](https://github.com/AreteDriver/memboot/actions/workflows/ci.yml/badge.svg)](https://github.com/AreteDriver/memboot/actions/workflows/ci.yml)
4
+ [![CodeQL](https://github.com/AreteDriver/memboot/actions/workflows/codeql.yml/badge.svg)](https://github.com/AreteDriver/memboot/actions/workflows/codeql.yml)
5
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
7
+
8
+ **Zero-infrastructure persistent memory for any LLM.**
9
+
10
+ Index your codebase, store decisions, and search everything with vector similarity — all local, all SQLite, no API keys needed.
11
+
12
+ ## Features
13
+
14
+ - **Smart chunking** — AST-aware Python extraction, Markdown heading splits, YAML/JSON key-level, sliding window fallback
15
+ - **Local embeddings** — Built-in TF-IDF (zero deps), optional sentence-transformers for semantic search
16
+ - **Episodic memory** — Store decisions, patterns, observations alongside your code index
17
+ - **Context builder** — Token-budgeted markdown blocks ready for LLM prompts
18
+ - **MCP server** — Expose memory as tools for Claude Code, Cursor, and other MCP clients (Pro)
19
+ - **File ingestion** — Ingest external files, PDFs, and web pages into project memory
20
+
21
+ ## Install
22
+
23
+ ```bash
24
+ pip install memboot
25
+ ```
26
+
27
+ Optional extras:
28
+
29
+ ```bash
30
+ pip install memboot[embed] # sentence-transformers for semantic embeddings
31
+ pip install memboot[mcp] # MCP server support
32
+ pip install memboot[pdf] # PDF ingestion
33
+ pip install memboot[watch] # File watching for auto-reindex
34
+ pip install memboot[web] # Web page ingestion
35
+ ```
36
+
37
+ ## Quick Start
38
+
39
+ ```bash
40
+ # Index a project
41
+ memboot init /path/to/your/project
42
+
43
+ # Search for relevant code and memories
44
+ memboot query "authentication flow" --project /path/to/your/project
45
+
46
+ # Store a decision
47
+ memboot remember "Use JWT for API auth, sessions for web" --type decision --project /path/to/your/project
48
+
49
+ # Get formatted context for an LLM prompt
50
+ memboot context "database schema" --project /path/to/your/project --max-tokens 4000
51
+
52
+ # Check license status
53
+ memboot status
54
+ ```
55
+
56
+ ## CLI Commands
57
+
58
+ | Command | Description |
59
+ |---------|-------------|
60
+ | `memboot init` | Scan, chunk, embed, and index a project |
61
+ | `memboot query` | Search project memory by similarity |
62
+ | `memboot remember` | Store an episodic memory (decision, note, observation, pattern) |
63
+ | `memboot context` | Export a formatted context block with token budget |
64
+ | `memboot status` | Show license tier and available features |
65
+ | `memboot reset` | Clear all indexed data and memories |
66
+ | `memboot ingest` | Add external files, PDFs, or URLs to memory |
67
+ | `memboot watch` | Watch project and auto-reindex on changes |
68
+ | `memboot serve` | Start MCP stdio server (Pro) |
69
+
70
+ ## How It Works
71
+
72
+ ```
73
+ Project Files ──→ Chunker ──→ Embedder ──→ SQLite Store
74
+ (AST) (TF-IDF) (~/.memboot/)
75
+
76
+ Query Text ─────→ Embedder ──→ Cosine Sim ──→ Results
77
+
78
+ Memories ───────→ Embedder ──→ Store ───────→ Searchable
79
+ ```
80
+
81
+ 1. **Index** — Recursively discover files, chunk by language (Python AST, Markdown headers, etc.), embed with TF-IDF, store in SQLite
82
+ 2. **Query** — Embed your query, compute cosine similarity against all chunks and memories, return top-K
83
+ 3. **Remember** — Store episodic memories (decisions, patterns, observations) with embeddings for later retrieval
84
+ 4. **Context** — Build token-budgeted markdown blocks with source attribution for LLM consumption
85
+
86
+ Each project gets its own SQLite database at `~/.memboot/{hash}.db`. No servers, no API keys, no network calls.
87
+
88
+ ## Architecture
89
+
90
+ ```
91
+ src/memboot/
92
+ ├── models.py # Pydantic v2 data models
93
+ ├── store.py # SQLite WAL backend (numpy BLOB serialization)
94
+ ├── chunker.py # Language-aware chunking (Python/MD/YAML/JSON/window)
95
+ ├── embedder.py # TF-IDF (built-in) + sentence-transformers (optional)
96
+ ├── indexer.py # Discovery → chunk → embed → store pipeline
97
+ ├── query.py # Cosine similarity search
98
+ ├── memory.py # Episodic memory CRUD
99
+ ├── context.py # Token-budgeted context builder
100
+ ├── licensing.py # Free/Pro tier management
101
+ ├── cli.py # 8 Typer CLI commands
102
+ ├── mcp_server.py # MCP stdio server (3 tools)
103
+ └── ingest/ # External file/PDF/web ingestion
104
+ ```
105
+
106
+ ## License
107
+
108
+ MIT
@@ -0,0 +1,75 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0", "setuptools-scm>=8.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "memboot"
7
+ version = "0.2.0"
8
+ description = "Zero-infrastructure persistent memory for any LLM"
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ requires-python = ">=3.11"
12
+ authors = [{name = "AreteDriver"}]
13
+ keywords = ["memory", "llm", "mcp", "embeddings", "vector-search", "ai", "rag"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Developers",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.11",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Topic :: Software Development :: Build Tools",
24
+ "Typing :: Typed",
25
+ ]
26
+ dependencies = [
27
+ "typer>=0.9.0",
28
+ "rich>=13.0",
29
+ "pydantic>=2.0",
30
+ "numpy>=1.24",
31
+ "pyyaml>=6.0",
32
+ ]
33
+
34
+ [project.optional-dependencies]
35
+ embed = ["sentence-transformers>=2.0"]
36
+ mcp = ["mcp>=1.0"]
37
+ pdf = ["pdfplumber>=0.10"]
38
+ watch = ["watchdog>=3.0"]
39
+ web = ["trafilatura>=1.6"]
40
+ dev = [
41
+ "pytest>=7.0",
42
+ "pytest-cov>=4.0",
43
+ "mypy>=1.0",
44
+ "ruff>=0.1.0",
45
+ "watchdog>=3.0",
46
+ ]
47
+
48
+ [project.scripts]
49
+ memboot = "memboot.cli:app"
50
+
51
+ [project.urls]
52
+ Homepage = "https://github.com/AreteDriver/memboot"
53
+ Repository = "https://github.com/AreteDriver/memboot"
54
+ Issues = "https://github.com/AreteDriver/memboot/issues"
55
+
56
+ [tool.setuptools.packages.find]
57
+ where = ["src"]
58
+
59
+ [tool.ruff]
60
+ line-length = 100
61
+ target-version = "py311"
62
+
63
+ [tool.ruff.lint]
64
+ select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM"]
65
+
66
+ [tool.ruff.lint.per-file-ignores]
67
+ "src/memboot/cli.py" = ["B008"]
68
+
69
+ [tool.pytest.ini_options]
70
+ testpaths = ["tests"]
71
+ addopts = "--cov=memboot --cov-report=term-missing --cov-fail-under=90"
72
+
73
+ [tool.mypy]
74
+ python_version = "3.11"
75
+ strict = true
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """memboot -- Zero-infrastructure persistent memory for any LLM."""
2
+
3
+ __version__ = "0.2.0"
4
+ __all__ = ["__version__"]