all41n14lla 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jordan Truong
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,158 @@
1
+ Metadata-Version: 2.4
2
+ Name: all41n14lla
3
+ Version: 0.1.0
4
+ Summary: Portable memory for AI agents. Markdown on your disk. Speaks MCP.
5
+ Author-email: Jordan Truong <emailme@jordantruong.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/bludragon-ai/all41n14lla
8
+ Project-URL: Repository, https://github.com/bludragon-ai/all41n14lla
9
+ Project-URL: Issues, https://github.com/bludragon-ai/all41n14lla/issues
10
+ Keywords: mcp,model-context-protocol,ai-agents,memory,markdown,sqlite,fts5,obsidian,claude,cursor,local-first,portable-memory
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
+ Classifier: Topic :: Text Processing :: Markup :: Markdown
19
+ Classifier: Operating System :: OS Independent
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: mcp>=0.9.0
24
+ Requires-Dist: typer>=0.12.0
25
+ Requires-Dist: pyyaml>=6.0
26
+ Requires-Dist: python-frontmatter>=1.1.0
27
+ Requires-Dist: watchdog>=4.0.0
28
+ Requires-Dist: rich>=13.7.0
29
+ Requires-Dist: httpx<1,>=0.27
30
+ Provides-Extra: dev
31
+ Requires-Dist: pytest>=8.0; extra == "dev"
32
+ Requires-Dist: pytest-cov; extra == "dev"
33
+ Requires-Dist: ruff; extra == "dev"
34
+ Requires-Dist: mypy; extra == "dev"
35
+ Dynamic: license-file
36
+
37
+ # all41n14lla
38
+
39
+ Portable memory for AI agents. Markdown on your disk. Speaks MCP.
40
+
41
+ [![Tests](https://github.com/bludragon-ai/all41n14lla/actions/workflows/test.yml/badge.svg)](https://github.com/bludragon-ai/all41n14lla/actions/workflows/test.yml)
42
+ [![PyPI](https://img.shields.io/pypi/v/all41n14lla.svg)](https://pypi.org/project/all41n14lla/)
43
+ [![Python](https://img.shields.io/pypi/pyversions/all41n14lla.svg)](https://pypi.org/project/all41n14lla/)
44
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
45
+
46
+ > **Status:** `v0.1.0a2` (alpha). The engine is real: SQLite + FTS5 index, MCP stdio server, four-type storage, live watchdog reconciliation, pathways edge auto-increment on episode writes. 26/26 tests passing on Python 3.13; CI matrix validates 3.11 / 3.12 / 3.13. A short demo video lands with v0.1.0 (non-alpha) after a 24-hour bake. Expect rough edges until then.
47
+
48
+ ## The problem
49
+
50
+ Agent memory is broken in five specific ways: models forget mid-session, hosted memory stores trap your data, memory does not cross agents, most stores are opaque blobs you cannot audit, and nothing works offline. The dominant "fix" — jam more context into the prompt — treats the language model as a storage engine. It is not one. It is a reasoning engine. Storage belongs on disk.
51
+
52
+ ## What this fixes
53
+
54
+ Memory should live where you can read it, back it up, grep it, diff it in git, and open it in a text editor. It should speak a protocol every MCP-capable client already supports, so swapping agents does not mean rebuilding your memory. It should be typed, because different kinds of memory deserve different retrieval policies.
55
+
56
+ `all41n14lla` stores memories as markdown files on your disk, indexes them locally with SQLite + FTS5, and exposes them over MCP stdio. Claude Code, Claude Desktop, Cursor, and anything else that speaks MCP gets `remember`, `recall`, `forget`, `inspect`, and `consolidate` for free. No SDK lock-in. No vendor cloud. No round trip. Your vault is yours.
57
+
58
+ ## How it works
59
+
60
+ Four node types, one vault, type-aware retrieval.
61
+
62
+ - **Concepts** — stable ideas and definitions. Long-lived. Surfaced when their topic comes up.
63
+ - **Patterns** — repeated behaviors. Derived from episodes, not written directly. Promoted when the repetition crosses a threshold.
64
+ - **Episodes** — specific events. High volume. Decay fast, because most stop mattering once the situation is over.
65
+ - **Constraints** — hard rules. Never decay. Always surfaced when their tags overlap the query. Non-negotiable.
66
+
67
+ Each lives in its own folder (`concepts/`, `patterns/`, `episodes/`, `constraints/`). Each is a markdown file with YAML frontmatter. You can edit them by hand — the `watchdog` observer reconciles changes into the index. Hand-editing is a supported workflow, not a workaround.
68
+
69
+ Retrieval is not one ranking function over one bucket. Concepts rank by match score plus tag overlap. Patterns add a moderate recency boost. Episodes add a stronger one. Constraints whose tags overlap the query are **always** returned, regardless of match score — hard rules are not allowed to silently drop out of a recall. Full architecture: [docs/architecture.md](docs/architecture.md).
70
+
71
+ ## Install
72
+
73
+ ### From PyPI (coming soon)
74
+
75
+ ```bash
76
+ pipx install all41n14lla
77
+ ```
78
+
79
+ Not published yet. Install from source in the meantime.
80
+
81
+ ### From source (works now)
82
+
83
+ ```bash
84
+ git clone https://github.com/bludragon-ai/all41n14lla.git
85
+ cd all41n14lla
86
+ python3.13 -m venv .venv
87
+ source .venv/bin/activate
88
+ pip install -e ".[dev]"
89
+ ```
90
+
91
+ Python 3.11+ works; 3.13 is what I develop against.
92
+
93
+ ## First run
94
+
95
+ ```bash
96
+ all41n14lla init # scaffolds ~/.all41n14lla/ (hidden dotfile vault)
97
+ all41n14lla remember concept "sqlite fts5 uses the porter tokenizer by default"
98
+ all41n14lla recall "sqlite tokenizer"
99
+ all41n14lla doctor # verify environment + vault health
100
+ ```
101
+
102
+ The default vault is `~/.all41n14lla/` — a hidden per-user dotfile. Pass `--path ~/memory` (or any other path) if you prefer a visible vault, e.g. one you open in Obsidian.
103
+
104
+ Other commands: `forget <id>`, `reconcile` (rebuild the index from disk), `inspect <query>` (stub in v0.1-alpha, full in v0.1 final), `consolidate` (stub, lands in v0.2), `version`, `serve`.
105
+
106
+ ## Claude Code / Claude Desktop / Cursor config
107
+
108
+ Drop this into the MCP config for your client of choice.
109
+
110
+ ```json
111
+ {
112
+ "mcpServers": {
113
+ "all41n14lla": {
114
+ "command": "all41n14lla",
115
+ "args": ["serve"]
116
+ }
117
+ }
118
+ }
119
+ ```
120
+
121
+ Transport is stdio. One process, one client. The server exposes `remember`, `recall`, `forget`, `inspect`, and `consolidate` as MCP tools.
122
+
123
+ ## Comparison
124
+
125
+ Every claim below was verified against the tool's current README or docs at the time of writing.
126
+
127
+ | Tool | Markdown-native | Typed retrieval (4 node types) | User-owned local vault | Offline-first | MCP-native | Embeddings | License |
128
+ | ------------------------------ | --------------- | ------------------------------ | ---------------------- | ------------- | ---------- | ---------- | ---------- |
129
+ | **all41n14lla** | Yes | Yes (concept/pattern/episode/constraint) | Yes | Yes | Yes | No (v0.1) | MIT |
130
+ | **Basic Memory** | Yes | Partial (observations + relations, not 4 fixed types) | Yes (local-first; optional paid cloud sync) | Yes | Yes | Yes (FastEmbed, hybrid FTS + vector) | AGPL-3.0 |
131
+ | **MemPalace** | No (verbatim text + SQLite + ChromaDB) | Partial (wings/rooms/drawers hierarchy) | Yes | Yes | Yes | Yes (local, ChromaDB default) | MIT |
132
+ | **mem0** | No (pluggable vector DB) | Partial (user/session/agent levels) | Only in library mode; cloud and self-hosted are the pitched paths | Library mode only | No (not MCP-native; LangGraph/CrewAI integrations) | Yes (OpenAI `text-embedding-3-small` default) | Apache-2.0 |
133
+ | **MCP Memory (reference)** | No (JSONL file) | No (user-defined entity types, no enforced taxonomy) | Yes (local JSONL) | Yes | Yes | No (text search only) | MIT |
134
+
135
+ Read the full comparison in [docs/comparison.md](docs/comparison.md).
136
+
137
+ ## Roadmap
138
+
139
+ - **v0.1 (this release)** — four node types, markdown on disk, SQLite + FTS5 index, MCP stdio server, watchdog reconciliation, CLI (`init`, `serve`, `doctor`, `remember`, `recall`, `forget`, `reconcile`, `version`). Lexical search only.
140
+ - **v0.2** — embedding-based semantic recall, pattern promotion from repeated episodes, decay on episodes, scheduled `consolidate` pass.
141
+ - **v0.3** — Obsidian plugin so the vault is a first-class notebook, graph view for nodes and links, bidirectional editing.
142
+
143
+ No dates. Ships when it ships.
144
+
145
+ ## Docs
146
+
147
+ - [Why](docs/why.md) — the thesis: what is broken about agent memory and why this shape fixes it.
148
+ - [Savant cognition as memory architecture](docs/savant-cognition.md) — the longer origin story. How a personal interest in typed, pattern-indexed, never-degrading memory became the shape of this project, grounded in a survey of 60+ existing agent-memory tools.
149
+ - [Architecture](docs/architecture.md) — how the engine actually works. Storage, frontmatter schema, retrieval flow, pathways, MCP surface.
150
+ - [Comparison](docs/comparison.md) — honest look at `all41n14lla` vs. Basic Memory, MemPalace, mem0, and the MCP reference server.
151
+ - [Origin](ORIGIN.md) — where the name comes from.
152
+ - [Quickstart — Claude Desktop](docs/quickstart-claude-desktop.md) — five-minute install-to-working guide for Claude Desktop users.
153
+
154
+ ## License
155
+
156
+ MIT. Copyright Jordan Truong.
157
+
158
+ Open-source inspirations visible in the style of this project: [santifer/career-ops](https://github.com/santifer/career-ops) and [cv-santiago](https://github.com/santifer/cv-santiago) — both good examples of useful, personal, no-fluff tooling.
@@ -0,0 +1,122 @@
1
+ # all41n14lla
2
+
3
+ Portable memory for AI agents. Markdown on your disk. Speaks MCP.
4
+
5
+ [![Tests](https://github.com/bludragon-ai/all41n14lla/actions/workflows/test.yml/badge.svg)](https://github.com/bludragon-ai/all41n14lla/actions/workflows/test.yml)
6
+ [![PyPI](https://img.shields.io/pypi/v/all41n14lla.svg)](https://pypi.org/project/all41n14lla/)
7
+ [![Python](https://img.shields.io/pypi/pyversions/all41n14lla.svg)](https://pypi.org/project/all41n14lla/)
8
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
+
10
+ > **Status:** `v0.1.0a2` (alpha). The engine is real: SQLite + FTS5 index, MCP stdio server, four-type storage, live watchdog reconciliation, pathways edge auto-increment on episode writes. 26/26 tests passing on Python 3.13; CI matrix validates 3.11 / 3.12 / 3.13. A short demo video lands with v0.1.0 (non-alpha) after a 24-hour bake. Expect rough edges until then.
11
+
12
+ ## The problem
13
+
14
+ Agent memory is broken in five specific ways: models forget mid-session, hosted memory stores trap your data, memory does not cross agents, most stores are opaque blobs you cannot audit, and nothing works offline. The dominant "fix" — jam more context into the prompt — treats the language model as a storage engine. It is not one. It is a reasoning engine. Storage belongs on disk.
15
+
16
+ ## What this fixes
17
+
18
+ Memory should live where you can read it, back it up, grep it, diff it in git, and open it in a text editor. It should speak a protocol every MCP-capable client already supports, so swapping agents does not mean rebuilding your memory. It should be typed, because different kinds of memory deserve different retrieval policies.
19
+
20
+ `all41n14lla` stores memories as markdown files on your disk, indexes them locally with SQLite + FTS5, and exposes them over MCP stdio. Claude Code, Claude Desktop, Cursor, and anything else that speaks MCP gets `remember`, `recall`, `forget`, `inspect`, and `consolidate` for free. No SDK lock-in. No vendor cloud. No round trip. Your vault is yours.
21
+
22
+ ## How it works
23
+
24
+ Four node types, one vault, type-aware retrieval.
25
+
26
+ - **Concepts** — stable ideas and definitions. Long-lived. Surfaced when their topic comes up.
27
+ - **Patterns** — repeated behaviors. Derived from episodes, not written directly. Promoted when the repetition crosses a threshold.
28
+ - **Episodes** — specific events. High volume. Decay fast, because most stop mattering once the situation is over.
29
+ - **Constraints** — hard rules. Never decay. Always surfaced when their tags overlap the query. Non-negotiable.
30
+
31
+ Each lives in its own folder (`concepts/`, `patterns/`, `episodes/`, `constraints/`). Each is a markdown file with YAML frontmatter. You can edit them by hand — the `watchdog` observer reconciles changes into the index. Hand-editing is a supported workflow, not a workaround.
32
+
33
+ Retrieval is not one ranking function over one bucket. Concepts rank by match score plus tag overlap. Patterns add a moderate recency boost. Episodes add a stronger one. Constraints whose tags overlap the query are **always** returned, regardless of match score — hard rules are not allowed to silently drop out of a recall. Full architecture: [docs/architecture.md](docs/architecture.md).
34
+
35
+ ## Install
36
+
37
+ ### From PyPI (coming soon)
38
+
39
+ ```bash
40
+ pipx install all41n14lla
41
+ ```
42
+
43
+ Not published yet. Install from source in the meantime.
44
+
45
+ ### From source (works now)
46
+
47
+ ```bash
48
+ git clone https://github.com/bludragon-ai/all41n14lla.git
49
+ cd all41n14lla
50
+ python3.13 -m venv .venv
51
+ source .venv/bin/activate
52
+ pip install -e ".[dev]"
53
+ ```
54
+
55
+ Python 3.11+ works; 3.13 is what I develop against.
56
+
57
+ ## First run
58
+
59
+ ```bash
60
+ all41n14lla init # scaffolds ~/.all41n14lla/ (hidden dotfile vault)
61
+ all41n14lla remember concept "sqlite fts5 uses the porter tokenizer by default"
62
+ all41n14lla recall "sqlite tokenizer"
63
+ all41n14lla doctor # verify environment + vault health
64
+ ```
65
+
66
+ The default vault is `~/.all41n14lla/` — a hidden per-user dotfile. Pass `--path ~/memory` (or any other path) if you prefer a visible vault, e.g. one you open in Obsidian.
67
+
68
+ Other commands: `forget <id>`, `reconcile` (rebuild the index from disk), `inspect <query>` (stub in v0.1-alpha, full in v0.1 final), `consolidate` (stub, lands in v0.2), `version`, `serve`.
69
+
70
+ ## Claude Code / Claude Desktop / Cursor config
71
+
72
+ Drop this into the MCP config for your client of choice.
73
+
74
+ ```json
75
+ {
76
+ "mcpServers": {
77
+ "all41n14lla": {
78
+ "command": "all41n14lla",
79
+ "args": ["serve"]
80
+ }
81
+ }
82
+ }
83
+ ```
84
+
85
+ Transport is stdio. One process, one client. The server exposes `remember`, `recall`, `forget`, `inspect`, and `consolidate` as MCP tools.
86
+
87
+ ## Comparison
88
+
89
+ Every claim below was verified against the tool's current README or docs at the time of writing.
90
+
91
+ | Tool | Markdown-native | Typed retrieval (4 node types) | User-owned local vault | Offline-first | MCP-native | Embeddings | License |
92
+ | ------------------------------ | --------------- | ------------------------------ | ---------------------- | ------------- | ---------- | ---------- | ---------- |
93
+ | **all41n14lla** | Yes | Yes (concept/pattern/episode/constraint) | Yes | Yes | Yes | No (v0.1) | MIT |
94
+ | **Basic Memory** | Yes | Partial (observations + relations, not 4 fixed types) | Yes (local-first; optional paid cloud sync) | Yes | Yes | Yes (FastEmbed, hybrid FTS + vector) | AGPL-3.0 |
95
+ | **MemPalace** | No (verbatim text + SQLite + ChromaDB) | Partial (wings/rooms/drawers hierarchy) | Yes | Yes | Yes | Yes (local, ChromaDB default) | MIT |
96
+ | **mem0** | No (pluggable vector DB) | Partial (user/session/agent levels) | Only in library mode; cloud and self-hosted are the pitched paths | Library mode only | No (not MCP-native; LangGraph/CrewAI integrations) | Yes (OpenAI `text-embedding-3-small` default) | Apache-2.0 |
97
+ | **MCP Memory (reference)** | No (JSONL file) | No (user-defined entity types, no enforced taxonomy) | Yes (local JSONL) | Yes | Yes | No (text search only) | MIT |
98
+
99
+ Read the full comparison in [docs/comparison.md](docs/comparison.md).
100
+
101
+ ## Roadmap
102
+
103
+ - **v0.1 (this release)** — four node types, markdown on disk, SQLite + FTS5 index, MCP stdio server, watchdog reconciliation, CLI (`init`, `serve`, `doctor`, `remember`, `recall`, `forget`, `reconcile`, `version`). Lexical search only.
104
+ - **v0.2** — embedding-based semantic recall, pattern promotion from repeated episodes, decay on episodes, scheduled `consolidate` pass.
105
+ - **v0.3** — Obsidian plugin so the vault is a first-class notebook, graph view for nodes and links, bidirectional editing.
106
+
107
+ No dates. Ships when it ships.
108
+
109
+ ## Docs
110
+
111
+ - [Why](docs/why.md) — the thesis: what is broken about agent memory and why this shape fixes it.
112
+ - [Savant cognition as memory architecture](docs/savant-cognition.md) — the longer origin story. How a personal interest in typed, pattern-indexed, never-degrading memory became the shape of this project, grounded in a survey of 60+ existing agent-memory tools.
113
+ - [Architecture](docs/architecture.md) — how the engine actually works. Storage, frontmatter schema, retrieval flow, pathways, MCP surface.
114
+ - [Comparison](docs/comparison.md) — honest look at `all41n14lla` vs. Basic Memory, MemPalace, mem0, and the MCP reference server.
115
+ - [Origin](ORIGIN.md) — where the name comes from.
116
+ - [Quickstart — Claude Desktop](docs/quickstart-claude-desktop.md) — five-minute install-to-working guide for Claude Desktop users.
117
+
118
+ ## License
119
+
120
+ MIT. Copyright Jordan Truong.
121
+
122
+ Open-source inspirations visible in the style of this project: [santifer/career-ops](https://github.com/santifer/career-ops) and [cv-santiago](https://github.com/santifer/cv-santiago) — both good examples of useful, personal, no-fluff tooling.
@@ -0,0 +1,75 @@
1
+ [project]
2
+ name = "all41n14lla"
3
+ version = "0.1.0"
4
+ description = "Portable memory for AI agents. Markdown on your disk. Speaks MCP."
5
+ readme = "README.md"
6
+ license = { text = "MIT" }
7
+ authors = [{ name = "Jordan Truong", email = "emailme@jordantruong.com" }]
8
+ requires-python = ">=3.11"
9
+ keywords = [
10
+ "mcp",
11
+ "model-context-protocol",
12
+ "ai-agents",
13
+ "memory",
14
+ "markdown",
15
+ "sqlite",
16
+ "fts5",
17
+ "obsidian",
18
+ "claude",
19
+ "cursor",
20
+ "local-first",
21
+ "portable-memory",
22
+ ]
23
+ classifiers = [
24
+ "Development Status :: 3 - Alpha",
25
+ "License :: OSI Approved :: MIT License",
26
+ "Programming Language :: Python :: 3.11",
27
+ "Programming Language :: Python :: 3.12",
28
+ "Programming Language :: Python :: 3.13",
29
+ "Intended Audience :: Developers",
30
+ "Topic :: Software Development :: Libraries :: Python Modules",
31
+ "Topic :: Text Processing :: Markup :: Markdown",
32
+ "Operating System :: OS Independent",
33
+ ]
34
+ dependencies = [
35
+ "mcp>=0.9.0",
36
+ "typer>=0.12.0",
37
+ "pyyaml>=6.0",
38
+ "python-frontmatter>=1.1.0",
39
+ "watchdog>=4.0.0",
40
+ "rich>=13.7.0",
41
+ "httpx>=0.27,<1",
42
+ ]
43
+
44
+ [project.optional-dependencies]
45
+ dev = ["pytest>=8.0", "pytest-cov", "ruff", "mypy"]
46
+
47
+ [project.scripts]
48
+ all41n14lla = "all41n14lla.cli:app"
49
+
50
+ [project.urls]
51
+ Homepage = "https://github.com/bludragon-ai/all41n14lla"
52
+ Repository = "https://github.com/bludragon-ai/all41n14lla"
53
+ Issues = "https://github.com/bludragon-ai/all41n14lla/issues"
54
+
55
+ [build-system]
56
+ requires = ["setuptools>=68", "wheel"]
57
+ build-backend = "setuptools.build_meta"
58
+
59
+ [tool.setuptools.packages.find]
60
+ where = ["src"]
61
+
62
+ [tool.pytest.ini_options]
63
+ testpaths = ["tests"]
64
+ pythonpath = ["src"]
65
+
66
+ [tool.ruff]
67
+ line-length = 100
68
+ target-version = "py311"
69
+
70
+ [tool.mypy]
71
+ python_version = "3.11"
72
+
73
+ [[tool.mypy.overrides]]
74
+ module = ["frontmatter"]
75
+ ignore_missing_imports = true
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """all41n14lla — Portable memory for AI agents."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,4 @@
1
+ from all41n14lla.cli import app
2
+
3
+ if __name__ == "__main__":
4
+ app()