brainctl 0.1.0__tar.gz

brainctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terrence Schonleber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brainctl-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: brainctl
+Version: 0.1.0
+Summary: A cognitive memory system for AI agents — episodic, semantic, and procedural memory with FTS5 search, vector embeddings, neuromodulation, and MCP server integration.
+Author: Terrence Schonleber
+License: MIT
+Project-URL: Homepage, https://github.com/TSchonleber/brainctl
+Project-URL: Repository, https://github.com/TSchonleber/brainctl
+Project-URL: Documentation, https://github.com/TSchonleber/brainctl/blob/main/ARCHITECTURE.md
+Keywords: ai,agents,memory,mcp,sqlite,cognitive-architecture
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.27.0; extra == "mcp"
+Provides-Extra: vec
+Requires-Dist: sqlite-vec>=0.1.0; extra == "vec"
+Provides-Extra: all
+Requires-Dist: mcp>=1.27.0; extra == "all"
+Requires-Dist: sqlite-vec>=0.1.0; extra == "all"
+Dynamic: license-file
+
+# brainctl
+
+A cognitive memory system for AI agents. Single SQLite file. No server required.
+
+```python
+from brainctl import Brain
+
+brain = Brain()
+brain.remember("User prefers dark mode")
+brain.search("dark mode")
+brain.entity("Alice", "person", observations=["Engineer", "Likes Python"])
+brain.relate("Alice", "works_at", "Acme")
+brain.log("Deployed v2.0")
+```
+
+## MCP Server (Claude Desktop / VS Code)
+
+```json
+{
+  "mcpServers": {
+    "brainctl": {
+      "command": "brainctl-mcp"
+    }
+  }
+}
+```
+
+12 tools: `memory_add`, `memory_search`, `event_add`, `event_search`, `entity_create`, `entity_get`, `entity_search`, `entity_observe`, `entity_relate`, `decision_add`, `search`, `stats`
+
+## Install
+
+```bash
+pip install brainctl              # core
+pip install brainctl[mcp]         # with MCP server
+pip install brainctl[vec]         # with vector search (sqlite-vec)
+pip install brainctl[all]         # everything
+```
+
+## CLI
+
+```bash
+# Memories
+brainctl memory add "Python 3.12 is the minimum version" -c convention
+brainctl memory search "python version"
+
+# Entities (typed knowledge graph)
+brainctl entity create "Alice" -t person -o "Engineer; Likes Python; Based in NYC"
+brainctl entity get Alice
+brainctl entity relate Alice works_at Acme
+brainctl entity search "engineer"
+
+# Events
+brainctl event add "Deployed v2.0 to production" -t result -p myproject
+brainctl event search -q "deploy"
+
+# Cross-table search (memories + events + entities)
+brainctl search "deployment"
+
+# Prospective memory (triggers that fire on future queries)
+brainctl trigger create "Alice mentions vacation" -k vacation,alice -a "Remind about project deadline"
+brainctl trigger check "alice is going on vacation"
+
+# Stats
+brainctl stats
+```
+
+## What Makes It Different
+
+| Feature | brainctl | mem0 | Zep | MemGPT |
+|---------|----------|------|-----|--------|
+| Single file (SQLite) | ✓ | ✗ | ✗ | ✗ |
+| No server required | ✓ | ✓ | ✗ | ✗ |
+| MCP server included | ✓ | ✗ | ✗ | ✗ |
+| Full-text search (FTS5) | ✓ | ✗ | ✗ | ✗ |
+| Vector search | ✓ | ✓ | ✓ | ✓ |
+| Entity registry | ✓ | ✗ | ✓ | ✗ |
+| Knowledge graph | ✓ | ✗ | ✓ | ✗ |
+| Consolidation engine | ✓ | ✗ | ✗ | ✗ |
+| Confidence decay | ✓ | ✗ | ✗ | ✗ |
+| Bayesian scoring | ✓ | ✗ | ✗ | ✗ |
+| Prospective memory | ✓ | ✗ | ✗ | ✗ |
+| Write gate (surprise scoring) | ✓ | ✗ | ✗ | ✗ |
+| Multi-agent support | ✓ | ✗ | ✓ | ✗ |
+| No LLM calls for memory ops | ✓ | ✗ | ✓ | ✗ |
+
+## Architecture
+
+```
+brain.db (single SQLite file)
+├── memories        FTS5 full-text + optional vec search
+├── events          timestamped logs with importance scoring
+├── entities        typed nodes (person, project, tool, concept...)
+├── knowledge_edges directed relations between any table rows
+├── decisions       recorded with rationale
+├── memory_triggers prospective memory (fire on future conditions)
+└── 20+ more tables (consolidation, beliefs, policies, epochs...)
+
+Consolidation Engine (hippocampus.py)
+├── Confidence decay    — unused memories fade
+├── Temporal promotion  — frequently-accessed memories strengthen
+├── Dream synthesis     — discover non-obvious connections
+├── Hebbian learning    — co-retrieved memories form edges
+├── Contradiction detection
+└── Compression         — merge redundant memories
+
+Write Gate (W(m))
+├── Surprise scoring    — reject redundant memories at the door
+├── Worthiness check    — surprise × importance × (1 - redundancy)
+└── Force flag          — bypass for explicit writes
+```
+
+## Vector Search (Optional)
+
+brainctl works without embeddings. For vector search, install Ollama and sqlite-vec:
+
+```bash
+pip install brainctl[vec]
+# Install Ollama: https://ollama.ai
+ollama pull nomic-embed-text
+brainctl-embed                    # backfill embeddings
+brainctl vsearch "semantic query" # vector similarity search
+```
+
+## Docker
+
+```bash
+docker build -t brainctl .
+docker run -v ./data:/data brainctl              # MCP server
+docker run -v ./data:/data brainctl brainctl stats  # CLI
+```
+
+## Multi-Agent
+
+Every operation accepts `--agent` / `agent_id` for attribution:
+
+```bash
+brainctl -a agent-alpha memory add "learned something" -c lesson
+brainctl -a agent-beta entity observe "Alice" "Now leads the team"
+```
+
+Agents share one brain.db. Each write is attributed. Search sees everything.
+
+## Contributing
+
+PRs welcome. The codebase is one big Python file (`bin/brainctl`) — intentionally. Single-file means no import hell, easy to read, easy to deploy.
+
+## License
+
+MIT

brainctl-0.1.0/README.md

@@ -0,0 +1,149 @@
+# brainctl
+
+A cognitive memory system for AI agents. Single SQLite file. No server required.
+
+```python
+from brainctl import Brain
+
+brain = Brain()
+brain.remember("User prefers dark mode")
+brain.search("dark mode")
+brain.entity("Alice", "person", observations=["Engineer", "Likes Python"])
+brain.relate("Alice", "works_at", "Acme")
+brain.log("Deployed v2.0")
+```
+
+## MCP Server (Claude Desktop / VS Code)
+
+```json
+{
+  "mcpServers": {
+    "brainctl": {
+      "command": "brainctl-mcp"
+    }
+  }
+}
+```
+
+12 tools: `memory_add`, `memory_search`, `event_add`, `event_search`, `entity_create`, `entity_get`, `entity_search`, `entity_observe`, `entity_relate`, `decision_add`, `search`, `stats`
+
+## Install
+
+```bash
+pip install brainctl              # core
+pip install brainctl[mcp]         # with MCP server
+pip install brainctl[vec]         # with vector search (sqlite-vec)
+pip install brainctl[all]         # everything
+```
+
+## CLI
+
+```bash
+# Memories
+brainctl memory add "Python 3.12 is the minimum version" -c convention
+brainctl memory search "python version"
+
+# Entities (typed knowledge graph)
+brainctl entity create "Alice" -t person -o "Engineer; Likes Python; Based in NYC"
+brainctl entity get Alice
+brainctl entity relate Alice works_at Acme
+brainctl entity search "engineer"
+
+# Events
+brainctl event add "Deployed v2.0 to production" -t result -p myproject
+brainctl event search -q "deploy"
+
+# Cross-table search (memories + events + entities)
+brainctl search "deployment"
+
+# Prospective memory (triggers that fire on future queries)
+brainctl trigger create "Alice mentions vacation" -k vacation,alice -a "Remind about project deadline"
+brainctl trigger check "alice is going on vacation"
+
+# Stats
+brainctl stats
+```
+
+## What Makes It Different
+
+| Feature | brainctl | mem0 | Zep | MemGPT |
+|---------|----------|------|-----|--------|
+| Single file (SQLite) | ✓ | ✗ | ✗ | ✗ |
+| No server required | ✓ | ✓ | ✗ | ✗ |
+| MCP server included | ✓ | ✗ | ✗ | ✗ |
+| Full-text search (FTS5) | ✓ | ✗ | ✗ | ✗ |
+| Vector search | ✓ | ✓ | ✓ | ✓ |
+| Entity registry | ✓ | ✗ | ✓ | ✗ |
+| Knowledge graph | ✓ | ✗ | ✓ | ✗ |
+| Consolidation engine | ✓ | ✗ | ✗ | ✗ |
+| Confidence decay | ✓ | ✗ | ✗ | ✗ |
+| Bayesian scoring | ✓ | ✗ | ✗ | ✗ |
+| Prospective memory | ✓ | ✗ | ✗ | ✗ |
+| Write gate (surprise scoring) | ✓ | ✗ | ✗ | ✗ |
+| Multi-agent support | ✓ | ✗ | ✓ | ✗ |
+| No LLM calls for memory ops | ✓ | ✗ | ✓ | ✗ |
+
+## Architecture
+
+```
+brain.db (single SQLite file)
+├── memories        FTS5 full-text + optional vec search
+├── events          timestamped logs with importance scoring
+├── entities        typed nodes (person, project, tool, concept...)
+├── knowledge_edges directed relations between any table rows
+├── decisions       recorded with rationale
+├── memory_triggers prospective memory (fire on future conditions)
+└── 20+ more tables (consolidation, beliefs, policies, epochs...)
+
+Consolidation Engine (hippocampus.py)
+├── Confidence decay    — unused memories fade
+├── Temporal promotion  — frequently-accessed memories strengthen
+├── Dream synthesis     — discover non-obvious connections
+├── Hebbian learning    — co-retrieved memories form edges
+├── Contradiction detection
+└── Compression         — merge redundant memories
+
+Write Gate (W(m))
+├── Surprise scoring    — reject redundant memories at the door
+├── Worthiness check    — surprise × importance × (1 - redundancy)
+└── Force flag          — bypass for explicit writes
+```
+
+## Vector Search (Optional)
+
+brainctl works without embeddings. For vector search, install Ollama and sqlite-vec:
+
+```bash
+pip install brainctl[vec]
+# Install Ollama: https://ollama.ai
+ollama pull nomic-embed-text
+brainctl-embed                    # backfill embeddings
+brainctl vsearch "semantic query" # vector similarity search
+```
+
+## Docker
+
+```bash
+docker build -t brainctl .
+docker run -v ./data:/data brainctl              # MCP server
+docker run -v ./data:/data brainctl brainctl stats  # CLI
+```
+
+## Multi-Agent
+
+Every operation accepts `--agent` / `agent_id` for attribution:
+
+```bash
+brainctl -a agent-alpha memory add "learned something" -c lesson
+brainctl -a agent-beta entity observe "Alice" "Now leads the team"
+```
+
+Agents share one brain.db. Each write is attributed. Search sees everything.
+
+## Contributing
+
+PRs welcome. The codebase is one big Python file (`bin/brainctl`) — intentionally. Single-file means no import hell, easy to read, easy to deploy.
+
+## License
+
+MIT

brainctl-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brainctl"
+version = "0.1.0"
+description = "A cognitive memory system for AI agents — episodic, semantic, and procedural memory with FTS5 search, vector embeddings, neuromodulation, and MCP server integration."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Terrence Schonleber"}
+]
+keywords = ["ai", "agents", "memory", "mcp", "sqlite", "cognitive-architecture"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.27.0"]
+vec = ["sqlite-vec>=0.1.0"]
+all = ["mcp>=1.27.0", "sqlite-vec>=0.1.0"]
+
+[project.scripts]
+brainctl = "agentmemory.cli:main"
+brainctl-mcp = "agentmemory.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/TSchonleber/brainctl"
+Repository = "https://github.com/TSchonleber/brainctl"
+Documentation = "https://github.com/TSchonleber/brainctl/blob/main/ARCHITECTURE.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+agentmemory = ["db/*.sql"]

brainctl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brainctl-0.1.0/src/agentmemory/__init__.py

@@ -0,0 +1,16 @@
+"""
+brainctl — A cognitive memory system for AI agents.
+
+Quick start:
+    from brainctl import Brain
+    
+    brain = Brain()
+    brain.remember("User prefers dark mode")
+    brain.search("preferences")
+"""
+
+__version__ = "0.1.0"
+
+from agentmemory.brain import Brain
+
+__all__ = ["Brain", "__version__"]