cogmem-agent 0.1.1__tar.gz

cogmem_agent-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.db
+.pytest_cache/
+.venv/

cogmem_agent-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akira Honjo
+
+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.

cogmem_agent-0.1.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: cogmem-agent
+Version: 0.1.1
+Summary: Human-like cognitive memory for AI agents — emotion-gated recall with adaptive forgetting
+Project-URL: Homepage, https://github.com/akira/cognitive-memory
+Project-URL: Repository, https://github.com/akira/cognitive-memory
+Author: Akira Honjo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,cognitive,llm,memory,semantic-search
+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.9
+Classifier: Programming Language :: Python :: 3.10
+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.9
+Requires-Dist: tomli>=1.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Cognitive Memory
+
+Human-like cognitive memory for AI agents — emotion-gated recall with adaptive forgetting.
+
+Unlike traditional vector databases that treat all memories equally, Cognitive Memory models how humans actually remember: emotionally significant experiences persist longer, while routine information naturally fades. This makes AI agents feel more natural and context-aware.
+
+## Key Features
+
+- **Emotion-gated recall**: Arousal scores modulate memory persistence
+- **Adaptive forgetting**: High-arousal memories decay slower (configurable half-life)
+- **Adaptive search gate**: Skips trivial queries (greetings, acknowledgments)
+- **FailOpen design**: Falls back to keyword search when embeddings are unavailable
+- **Zero required dependencies**: Core uses only Python stdlib (sqlite3, urllib)
+- **Pluggable embeddings**: Ollama (built-in), OpenAI, or any custom provider
+
+## Install
+
+```bash
+pip install cognitive-memory
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+cogmem init                        # Initialize project
+cogmem index                       # Build/update index
+cogmem search "past decisions"     # Search memories
+cogmem status                      # Show statistics
+```
+
+### Python API
+
+```python
+from cognitive_memory import MemoryStore, CogMemConfig
+
+config = CogMemConfig.from_toml("cogmem.toml")
+with MemoryStore(config) as store:
+    store.index_dir()
+    result = store.search("past competition analysis")
+    for r in result.results:
+        print(f"{r.date} [{r.score:.2f}] {r.content[:80]}")
+```
+
+### Convenience API
+
+```python
+from cognitive_memory import search
+result = search("past decisions")  # Auto-finds cogmem.toml
+```
+
+## Scoring Formula
+
+```
+score = (0.7 * cosine_sim + 0.3 * arousal) * time_decay
+```
+
+Where `time_decay` uses an adaptive half-life:
+```
+half_life = base_half_life * (1 + arousal)
+```
+
+High-arousal memories (insights, conflicts, surprises) decay slower — just like human memory.
+
+## Configuration
+
+`cogmem.toml`:
+
+```toml
+[cogmem]
+logs_dir = "memory/logs"
+db_path = "memory/vectors.db"
+
+[cogmem.scoring]
+sim_weight = 0.7
+arousal_weight = 0.3
+base_half_life = 60.0
+decay_floor = 0.3
+
+[cogmem.embedding]
+provider = "ollama"
+model = "zylonai/multilingual-e5-large"
+url = "http://localhost:11434/api/embed"
+timeout = 10
+```
+
+## Custom Embedding Provider
+
+```python
+class MyEmbedder:
+    def embed(self, text: str) -> list[float] | None: ...
+    def embed_batch(self, texts: list[str]) -> list[list[float]] | None: ...
+
+store = MemoryStore(config, embedder=MyEmbedder())
+```
+
+## Documentation
+
+- [Quick Start](docs/quickstart.md)
+- [Log Format](docs/log-format.md)
+- [Embedding Providers](docs/embedding-providers.md)
+
+## License
+
+MIT

cogmem_agent-0.1.1/README.md

@@ -0,0 +1,106 @@
+# Cognitive Memory
+
+Human-like cognitive memory for AI agents — emotion-gated recall with adaptive forgetting.
+
+Unlike traditional vector databases that treat all memories equally, Cognitive Memory models how humans actually remember: emotionally significant experiences persist longer, while routine information naturally fades. This makes AI agents feel more natural and context-aware.
+
+## Key Features
+
+- **Emotion-gated recall**: Arousal scores modulate memory persistence
+- **Adaptive forgetting**: High-arousal memories decay slower (configurable half-life)
+- **Adaptive search gate**: Skips trivial queries (greetings, acknowledgments)
+- **FailOpen design**: Falls back to keyword search when embeddings are unavailable
+- **Zero required dependencies**: Core uses only Python stdlib (sqlite3, urllib)
+- **Pluggable embeddings**: Ollama (built-in), OpenAI, or any custom provider
+
+## Install
+
+```bash
+pip install cognitive-memory
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+cogmem init                        # Initialize project
+cogmem index                       # Build/update index
+cogmem search "past decisions"     # Search memories
+cogmem status                      # Show statistics
+```
+
+### Python API
+
+```python
+from cognitive_memory import MemoryStore, CogMemConfig
+
+config = CogMemConfig.from_toml("cogmem.toml")
+with MemoryStore(config) as store:
+    store.index_dir()
+    result = store.search("past competition analysis")
+    for r in result.results:
+        print(f"{r.date} [{r.score:.2f}] {r.content[:80]}")
+```
+
+### Convenience API
+
+```python
+from cognitive_memory import search
+result = search("past decisions")  # Auto-finds cogmem.toml
+```
+
+## Scoring Formula
+
+```
+score = (0.7 * cosine_sim + 0.3 * arousal) * time_decay
+```
+
+Where `time_decay` uses an adaptive half-life:
+```
+half_life = base_half_life * (1 + arousal)
+```
+
+High-arousal memories (insights, conflicts, surprises) decay slower — just like human memory.
+
+## Configuration
+
+`cogmem.toml`:
+
+```toml
+[cogmem]
+logs_dir = "memory/logs"
+db_path = "memory/vectors.db"
+
+[cogmem.scoring]
+sim_weight = 0.7
+arousal_weight = 0.3
+base_half_life = 60.0
+decay_floor = 0.3
+
+[cogmem.embedding]
+provider = "ollama"
+model = "zylonai/multilingual-e5-large"
+url = "http://localhost:11434/api/embed"
+timeout = 10
+```
+
+## Custom Embedding Provider
+
+```python
+class MyEmbedder:
+    def embed(self, text: str) -> list[float] | None: ...
+    def embed_batch(self, texts: list[str]) -> list[list[float]] | None: ...
+
+store = MemoryStore(config, embedder=MyEmbedder())
+```
+
+## Documentation
+
+- [Quick Start](docs/quickstart.md)
+- [Log Format](docs/log-format.md)
+- [Embedding Providers](docs/embedding-providers.md)
+
+## License
+
+MIT

cogmem_agent-0.1.1/docs/embedding-providers.md

@@ -0,0 +1,90 @@
+# Embedding Providers
+
+Cognitive Memory uses a Protocol-based embedding system. Any object with `embed()` and `embed_batch()` methods works.
+
+## Built-in: Ollama (Default)
+
+Zero external dependencies. Uses `urllib.request` to call Ollama's API.
+
+```toml
+[cogmem.embedding]
+provider = "ollama"
+model = "zylonai/multilingual-e5-large"
+url = "http://localhost:11434/api/embed"
+timeout = 10
+```
+
+### Setup
+
+```bash
+# Install Ollama (https://ollama.ai)
+ollama pull zylonai/multilingual-e5-large
+```
+
+### Recommended Models
+
+| Model | Size | Languages | Notes |
+|-------|------|-----------|-------|
+| `zylonai/multilingual-e5-large` | 2.2 GB | 100+ | Best for multilingual (recommended) |
+| `nomic-embed-text` | 274 MB | English | Lightweight, English-focused |
+| `mxbai-embed-large` | 670 MB | English | Good quality, moderate size |
+
+## Custom Provider
+
+Implement two methods:
+
+```python
+from typing import List, Optional
+
+class MyEmbedder:
+    def embed(self, text: str) -> Optional[List[float]]:
+        """Embed a single text. Return None on failure."""
+        ...
+
+    def embed_batch(self, texts: List[str]) -> Optional[List[List[float]]]:
+        """Embed multiple texts. Return None on failure."""
+        ...
+```
+
+Pass to MemoryStore:
+
+```python
+from cognitive_memory import MemoryStore, CogMemConfig
+
+store = MemoryStore(config, embedder=MyEmbedder())
+```
+
+## OpenAI Provider (Example)
+
+```bash
+pip install cognitive-memory[openai]
+```
+
+```python
+import openai
+
+class OpenAIEmbedding:
+    def __init__(self, model="text-embedding-3-small"):
+        self.client = openai.OpenAI()
+        self.model = model
+
+    def embed(self, text):
+        r = self.client.embeddings.create(input=[text], model=self.model)
+        return r.data[0].embedding
+
+    def embed_batch(self, texts):
+        r = self.client.embeddings.create(input=texts, model=self.model)
+        return [d.embedding for d in r.data]
+
+store = MemoryStore(config, embedder=OpenAIEmbedding())
+```
+
+## FailOpen Behavior
+
+If embedding fails (Ollama down, network error, etc.), Cognitive Memory falls back to keyword-based grep search. This ensures the system always returns results when possible.
+
+Search response status indicates the mode:
+- `"ok"` — Full semantic + grep search
+- `"degraded (ollama_unavailable)"` — Grep only (embedding failed)
+- `"degraded (no_index)"` — Grep only (no SQLite database)
+- `"skipped_by_gate"` — Query too short/trivial, no search performed

cogmem_agent-0.1.1/docs/log-format.md

@@ -0,0 +1,88 @@
+# Log Format Specification
+
+Cognitive Memory parses structured markdown log files to build a searchable memory index.
+
+## File Naming
+
+```
+memory/logs/YYYY-MM-DD.md
+```
+
+Files must start with a date pattern (`YYYY-MM-DD`). Files without this pattern are ignored.
+Files ending in `.compact.md` are excluded from indexing (they are compressed summaries).
+
+## File Structure
+
+```markdown
+# YYYY-MM-DD Session Log
+
+## Session Summary
+[Optional summary, not indexed]
+
+## Log Entries
+
+### [CATEGORY][DOMAIN] Entry Title
+*Arousal: 0.7 | Emotion: Insight*
+Entry content here. Must be at least 20 characters to pass noise filter.
+
+---
+
+### [CATEGORY][DOMAIN] Another Entry
+*Arousal: 0.5 | Emotion: Determination*
+More content here.
+
+---
+
+## 引き継ぎ
+[Everything below this delimiter is excluded from indexing]
+```
+
+## Category Tags
+
+| Tag | Usage |
+|-----|-------|
+| `[INSIGHT]` | New understanding, perspective shift |
+| `[DECISION]` | Decision and its rationale |
+| `[ERROR]` | Mistakes, failed assumptions, course corrections |
+| `[PATTERN]` | Recurring themes, behaviors, thought patterns |
+| `[QUESTION]` | Open questions, areas needing investigation |
+| `[MILESTONE]` | Important achievements, phase transitions |
+
+## Domain Tags
+
+Combine with category tags: `[INSIGHT][TECH]`, `[DECISION][MARKET]`
+
+Available: `[PROBLEM]` `[USER-RESEARCH]` `[MARKET]` `[CONCEPT]` `[BUSINESS-MODEL]` `[MVP]` `[TECH]` `[STRATEGY]` `[RISK]`
+
+## Arousal
+
+The `*Arousal: X.X | Emotion: ...*` line is optional but recommended.
+
+- **Range**: 0.0 to 1.0
+- **Default**: 0.5 (when not specified)
+- **Effect**: Higher arousal → slower forgetting (adaptive half-life), higher search score
+
+| Arousal | Meaning | Half-life (base=60d) |
+|---------|---------|---------------------|
+| 0.0 | Routine | 60 days |
+| 0.5 | Notable | 90 days |
+| 0.8 | Important | 108 days |
+| 1.0 | Critical | 120 days |
+
+## Noise Filter
+
+Entries are excluded if:
+- Content is shorter than 20 characters
+- Content matches noise patterns (greetings, acknowledgments)
+
+## Handover Delimiter
+
+Default: `## 引き継ぎ`
+
+Configurable in `cogmem.toml`:
+```toml
+[cogmem]
+handover_delimiter = "## Handover"
+```
+
+Everything after this delimiter is excluded from indexing.

cogmem_agent-0.1.1/docs/quickstart.md

@@ -0,0 +1,109 @@
+# Quick Start
+
+## Installation
+
+```bash
+pip install cognitive-memory
+```
+
+For OpenAI embedding support:
+```bash
+pip install cognitive-memory[openai]
+```
+
+## Project Setup
+
+```bash
+cogmem init
+```
+
+This creates:
+- `cogmem.toml` — configuration file
+- `memory/logs/` — directory for session logs
+- `.gitignore` update (excludes `*.db`)
+
+## Writing Logs
+
+Create markdown files in `memory/logs/` with the naming pattern `YYYY-MM-DD.md`:
+
+```markdown
+# 2026-03-21 Session Log
+
+## Log Entries
+
+### [INSIGHT][TECH] Discovered adaptive half-life
+*Arousal: 0.8 | Emotion: Insight*
+High-arousal memories should decay slower. Using formula:
+half_life = base * (1 + arousal)
+
+---
+
+### [DECISION][TECH] Chose SQLite over LanceDB
+*Arousal: 0.6 | Emotion: Determination*
+SQLite is sufficient for our scale. Zero external dependencies.
+
+---
+
+## 引き継ぎ
+- Content below this delimiter is excluded from search
+```
+
+## Building the Index
+
+```bash
+cogmem index          # Incremental (new/changed files only)
+cogmem index --all    # Force re-index everything
+```
+
+## Searching
+
+```bash
+cogmem search "adaptive half-life"
+cogmem search "competition analysis" --top-k 3
+cogmem search "previous decisions" --json
+```
+
+## Python API
+
+```python
+from cognitive_memory import MemoryStore, CogMemConfig
+
+config = CogMemConfig.from_toml("cogmem.toml")
+with MemoryStore(config) as store:
+    store.index_dir()
+    response = store.search("past competition analysis")
+    for r in response.results:
+        print(f"{r.date} [{r.score:.2f}] {r.content[:80]}")
+```
+
+### Convenience API
+
+```python
+from cognitive_memory import search
+
+response = search("past decisions")  # Auto-finds cogmem.toml
+```
+
+## AI Coding Tool Integration
+
+### Claude Code
+
+Add to `.claude/commands/search.md`:
+```
+Run `cogmem search "$ARGUMENTS"` and return the results.
+```
+
+### Cursor
+
+Add to `.cursorrules`:
+```
+Before answering questions about past decisions, run:
+cogmem search "<relevant query>"
+```
+
+### Cline
+
+Add to `.clinerules`:
+```
+Use `cogmem search` to recall past context before making decisions.
+```

cogmem_agent-0.1.1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cogmem-agent"
+dynamic = ["version"]
+description = "Human-like cognitive memory for AI agents — emotion-gated recall with adaptive forgetting"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Akira Honjo" }]
+keywords = ["ai", "agent", "memory", "cognitive", "semantic-search", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "tomli>=1.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+cogmem = "cognitive_memory.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/akira/cognitive-memory"
+Repository = "https://github.com/akira/cognitive-memory"
+
+[tool.hatch.version]
+path = "src/cognitive_memory/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cognitive_memory"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: requires Ollama running",
+]

cogmem_agent-0.1.1/src/cognitive_memory/__init__.py

@@ -0,0 +1,27 @@
+"""Cognitive Memory — human-like cognitive memory for AI agents."""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .config import CogMemConfig
+from .store import MemoryStore
+from .types import MemoryEntry, SearchResponse, SearchResult
+
+
+def search(query: str, top_k: int = 5, config: CogMemConfig | None = None) -> SearchResponse:
+    """Convenience function: auto-find cogmem.toml and search."""
+    if config is None:
+        config = CogMemConfig.find_and_load()
+    with MemoryStore(config) as store:
+        return store.search(query, top_k)
+
+
+__all__ = [
+    "__version__",
+    "CogMemConfig",
+    "MemoryEntry",
+    "MemoryStore",
+    "SearchResponse",
+    "SearchResult",
+    "search",
+]

cogmem_agent-0.1.1/src/cognitive_memory/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

cogmem_agent-0.1.1/src/cognitive_memory/cli/index_cmd.py

@@ -0,0 +1,42 @@
+"""cogmem index / cogmem status — index management commands."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+from ..config import CogMemConfig
+from ..store import MemoryStore
+
+
+def run_index(all_files: bool = False, single_file: str | None = None):
+    config = CogMemConfig.find_and_load()
+
+    with MemoryStore(config) as store:
+        t0 = time.time()
+
+        if single_file:
+            fp = config.logs_path / Path(single_file).name
+            if not fp.exists():
+                print(f"File not found: {fp}", file=sys.stderr)
+                sys.exit(1)
+            n = store.index_file(fp, force=True)
+            print(f"Indexed {n} entries from {fp.name}")
+        else:
+            n = store.index_dir(force=all_files)
+            elapsed = time.time() - t0
+            print(f"Done: {n} entries indexed in {elapsed:.1f}s")
+
+
+def run_status():
+    config = CogMemConfig.find_and_load()
+
+    with MemoryStore(config) as store:
+        stats = store.status()
+
+    print(f"Indexed files: {stats['indexed_files']}")
+    print(f"Total entries: {stats['total_entries']}")
+    size_kb = stats["db_size_bytes"] / 1024
+    print(f"Database size: {size_kb:.1f} KB")