devenv-ai 0.1.0__tar.gz

devenv_ai-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: devenv-ai
+Version: 0.1.0
+Summary: Local-first coding agent foundations.
+Author: Devenv Contributors
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: lancedb>=0.16.0
+Requires-Dist: mcp[cli]>=1.28.0
+Requires-Dist: sentence-transformers>=3.0.0
+
+# Devenv
+
+Devenv is a local-first coding agent project. The current implemented foundation is the **Cognitive Memory Engine (CME)** described in the PRDs under [`core/memory/prd_objective.md`](/Users/samarthnaik/Desktop/Projects/devenv/core/memory/prd_objective.md:1) and [`core/memory/prd_tech.md`](/Users/samarthnaik/Desktop/Projects/devenv/core/memory/prd_tech.md:1).
+
+Today, this repository is centered on a working Python package, `core.memory`, plus a small tools foundation. The memory engine is built to remove the idea of isolated chat sessions and instead support continuous, auditable memory across:
+
+- working memory for the current task window
+- episodic memory for timestamped interaction history
+- associative memory for structured project, component, and preference recall
+- consolidation for turning raw logs into reusable memory nodes
+
+## What Is Done
+
+The following PRD-driven functionality is implemented in this repository today:
+
+- A decoupled `MemoryEngine` interface in `core.memory` with injectable storage, embeddings, vector index, and consolidation extractor.
+- Working memory support with a bounded recent-message buffer and active session state snapshot.
+- Episodic memory logging with timestamped user/agent interactions and optional metadata.
+- Associative memory storage in SQLite using hierarchical nodes plus lateral graph edges.
+- Vector-backed semantic lookup for associative summaries.
+- Retrieval with spreading-activation behavior:
+  parent-chain expansion, sibling expansion, related-edge expansion, normalized ranking, and markdown context compilation.
+- Dynamic ranking signals based on similarity, access frequency, and recency.
+- Auditable retrieval traces through `get_context_trace()`, including matched nodes, expanded candidates, selected nodes, and the final injected markdown block.
+- Manual memory correction through `forget_node()` with both `prune` and `rewrite` strategies.
+- Consolidation flow that processes new episodic logs, creates new nodes, updates existing nodes, refreshes vectors, and stores a consolidation watermark.
+- A deterministic heuristic extractor seam so consolidation is testable without a live LLM.
+- Unit tests covering imports, storage, working memory, retrieval, consolidation, manual control, and vector lookup behavior.
+
+## PRD Alignment
+
+The current implementation covers a substantial part of the memory PRDs:
+
+- **Working Memory Manager:** implemented
+- **Episodic Memory timeline:** implemented
+- **Associative tree / graph structure:** implemented with SQLite nodes and edges
+- **Spreading activation retrieval:** implemented
+- **Importance and decay scoring:** implemented through normalized similarity, frequency, and recency scoring
+- **Auditable context trace:** implemented
+- **Manual memory correction:** implemented
+- **Asynchronous sleep consolidation:** partially implemented
+  the consolidation service exists and is ready to be called as a background task, but the repo does not yet include an always-on inactivity scheduler or terminal-event trigger loop
+
+## Current Architecture
+
+### `core.memory`
+
+Main public entry point:
+
+```python
+from core.memory import MemoryEngine
+
+engine = MemoryEngine(db_path="memory.db", vector_dir="vectors")
+```
+
+Implemented responsibilities:
+
+- `record_working_memory(messages, active_state)`
+- `add_episodic_log(user_prompt, agent_response, node_id=None, metadata=None)`
+- `update_associative_tree(node_data)`
+- `retrieve_context(current_prompt, top_k=5)`
+- `run_consolidation(since=None)`
+- `forget_node(node_id, strategy="prune")`
+- `get_context_trace()`
+
+Storage model:
+
+- **SQLite** stores:
+  `memory_nodes`, `node_edges`, `episodic_logs`, and engine state such as the last consolidation watermark.
+- **LanceDB** is the production vector store for associative summaries.
+- **In-memory test doubles** exist for the vector index and embedder so the system can be tested quickly and deterministically.
+
+### `core.tools`
+
+There is also a small tools foundation already implemented:
+
+- `BaseTool`
+- `ToolResult`
+- `ReadFileTool`
+
+`ReadFileTool` supports content reads plus optional metadata and extension analysis in one call.
+
+## Repository Layout
+
+```text
+core/
+  memory/
+    README.md
+    prd_objective.md
+    prd_tech.md
+    interface.py
+    engine.py
+    retrieval.py
+    consolidation.py
+    storage.py
+    vector_index.py
+    embeddings.py
+    working_memory.py
+    extractors.py
+    models.py
+  tools/
+    base.py
+    read_file.py
+tests/
+  memory/
+pyproject.toml
+README.md
+```
+
+## Setup
+
+Python 3.12+ is required.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e .
+```
+
+The production memory stack expects these local dependencies:
+
+- `lancedb`
+- `sentence-transformers`
+
+The test suite primarily uses lightweight in-memory test doubles instead of the production embedding/vector stack.
+
+## Example
+
+```python
+from core.memory import MemoryEngine
+
+engine = MemoryEngine(db_path="memory.db", vector_dir="vectors")
+
+engine.record_working_memory(
+    messages=[{"role": "user", "content": "Fix the Django auth flow"}],
+    active_state={"file": "core/memory/engine.py"},
+)
+
+engine.update_associative_tree(
+    {
+        "node_id": "proj_rxgpt",
+        "label": "Project: RxGPT",
+        "category": "project",
+        "summary": "RxGPT uses React, Tailwind, and Django.",
+    }
+)
+
+engine.add_episodic_log(
+    "We introduced a Django auth component.",
+    "I'll remember the backend shape.",
+    node_id="proj_rxgpt",
+    metadata={
+        "project": "RxGPT",
+        "memory_entities": [
+            {
+                "node_id": "cmp_django_auth",
+                "label": "Django Auth Setup",
+                "category": "component",
+                "summary": "Django auth relies on session cookies and middleware.",
+                "parent_id": "proj_rxgpt",
+            }
+        ],
+    },
+)
+
+engine.run_consolidation()
+result = engine.retrieve_context("How do I fix my django authentication errors?")
+
+print(result.markdown_context)
+print(engine.get_context_trace())
+```
+
+## Tests
+
+Run the memory test suite with:
+
+```bash
+python3 -m unittest discover -s tests -p 'test_*.py'
+```
+
+The current suite covers:
+
+- import boundaries
+- working memory bounds and snapshots
+- episodic log persistence
+- associative node and edge storage
+- vector index ranking
+- hierarchical retrieval and preference recall
+- retrieval trace scoring normalization
+- manual prune and rewrite behavior
+- consolidation creation, update, and watermark behavior
+
+## Not Done Yet
+
+The README should be clear about what is still future scope from the PRDs:
+
+- no CLI, web UI, or phone companion is implemented yet
+- no always-on background scheduler for inactivity-based consolidation yet
+- no cross-device sync yet
+- no multi-repo memory sharing yet
+- no full agent orchestration loop yet
+- no secure remote execution layer yet
+
+## Development Notes
+
+- The code is organized to keep memory logic decoupled from future UI or agent layers.
+- Tests use dependency injection heavily so memory behavior can be verified without external services.
+- The local-first constraint from the PRDs is preserved in the package design: raw logs, structured memory, and vector lookup are intended to live on the user machine.
+
+./.venv/bin/python -m core.runtime.web sample-test

devenv_ai-0.1.0/README.md

@@ -0,0 +1,211 @@
+# Devenv
+
+Devenv is a local-first coding agent project. The current implemented foundation is the **Cognitive Memory Engine (CME)** described in the PRDs under [`core/memory/prd_objective.md`](/Users/samarthnaik/Desktop/Projects/devenv/core/memory/prd_objective.md:1) and [`core/memory/prd_tech.md`](/Users/samarthnaik/Desktop/Projects/devenv/core/memory/prd_tech.md:1).
+
+Today, this repository is centered on a working Python package, `core.memory`, plus a small tools foundation. The memory engine is built to remove the idea of isolated chat sessions and instead support continuous, auditable memory across:
+
+- working memory for the current task window
+- episodic memory for timestamped interaction history
+- associative memory for structured project, component, and preference recall
+- consolidation for turning raw logs into reusable memory nodes
+
+## What Is Done
+
+The following PRD-driven functionality is implemented in this repository today:
+
+- A decoupled `MemoryEngine` interface in `core.memory` with injectable storage, embeddings, vector index, and consolidation extractor.
+- Working memory support with a bounded recent-message buffer and active session state snapshot.
+- Episodic memory logging with timestamped user/agent interactions and optional metadata.
+- Associative memory storage in SQLite using hierarchical nodes plus lateral graph edges.
+- Vector-backed semantic lookup for associative summaries.
+- Retrieval with spreading-activation behavior:
+  parent-chain expansion, sibling expansion, related-edge expansion, normalized ranking, and markdown context compilation.
+- Dynamic ranking signals based on similarity, access frequency, and recency.
+- Auditable retrieval traces through `get_context_trace()`, including matched nodes, expanded candidates, selected nodes, and the final injected markdown block.
+- Manual memory correction through `forget_node()` with both `prune` and `rewrite` strategies.
+- Consolidation flow that processes new episodic logs, creates new nodes, updates existing nodes, refreshes vectors, and stores a consolidation watermark.
+- A deterministic heuristic extractor seam so consolidation is testable without a live LLM.
+- Unit tests covering imports, storage, working memory, retrieval, consolidation, manual control, and vector lookup behavior.
+
+## PRD Alignment
+
+The current implementation covers a substantial part of the memory PRDs:
+
+- **Working Memory Manager:** implemented
+- **Episodic Memory timeline:** implemented
+- **Associative tree / graph structure:** implemented with SQLite nodes and edges
+- **Spreading activation retrieval:** implemented
+- **Importance and decay scoring:** implemented through normalized similarity, frequency, and recency scoring
+- **Auditable context trace:** implemented
+- **Manual memory correction:** implemented
+- **Asynchronous sleep consolidation:** partially implemented
+  the consolidation service exists and is ready to be called as a background task, but the repo does not yet include an always-on inactivity scheduler or terminal-event trigger loop
+
+## Current Architecture
+
+### `core.memory`
+
+Main public entry point:
+
+```python
+from core.memory import MemoryEngine
+
+engine = MemoryEngine(db_path="memory.db", vector_dir="vectors")
+```
+
+Implemented responsibilities:
+
+- `record_working_memory(messages, active_state)`
+- `add_episodic_log(user_prompt, agent_response, node_id=None, metadata=None)`
+- `update_associative_tree(node_data)`
+- `retrieve_context(current_prompt, top_k=5)`
+- `run_consolidation(since=None)`
+- `forget_node(node_id, strategy="prune")`
+- `get_context_trace()`
+
+Storage model:
+
+- **SQLite** stores:
+  `memory_nodes`, `node_edges`, `episodic_logs`, and engine state such as the last consolidation watermark.
+- **LanceDB** is the production vector store for associative summaries.
+- **In-memory test doubles** exist for the vector index and embedder so the system can be tested quickly and deterministically.
+
+### `core.tools`
+
+There is also a small tools foundation already implemented:
+
+- `BaseTool`
+- `ToolResult`
+- `ReadFileTool`
+
+`ReadFileTool` supports content reads plus optional metadata and extension analysis in one call.
+
+## Repository Layout
+
+```text
+core/
+  memory/
+    README.md
+    prd_objective.md
+    prd_tech.md
+    interface.py
+    engine.py
+    retrieval.py
+    consolidation.py
+    storage.py
+    vector_index.py
+    embeddings.py
+    working_memory.py
+    extractors.py
+    models.py
+  tools/
+    base.py
+    read_file.py
+tests/
+  memory/
+pyproject.toml
+README.md
+```
+
+## Setup
+
+Python 3.12+ is required.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e .
+```
+
+The production memory stack expects these local dependencies:
+
+- `lancedb`
+- `sentence-transformers`
+
+The test suite primarily uses lightweight in-memory test doubles instead of the production embedding/vector stack.
+
+## Example
+
+```python
+from core.memory import MemoryEngine
+
+engine = MemoryEngine(db_path="memory.db", vector_dir="vectors")
+
+engine.record_working_memory(
+    messages=[{"role": "user", "content": "Fix the Django auth flow"}],
+    active_state={"file": "core/memory/engine.py"},
+)
+
+engine.update_associative_tree(
+    {
+        "node_id": "proj_rxgpt",
+        "label": "Project: RxGPT",
+        "category": "project",
+        "summary": "RxGPT uses React, Tailwind, and Django.",
+    }
+)
+
+engine.add_episodic_log(
+    "We introduced a Django auth component.",
+    "I'll remember the backend shape.",
+    node_id="proj_rxgpt",
+    metadata={
+        "project": "RxGPT",
+        "memory_entities": [
+            {
+                "node_id": "cmp_django_auth",
+                "label": "Django Auth Setup",
+                "category": "component",
+                "summary": "Django auth relies on session cookies and middleware.",
+                "parent_id": "proj_rxgpt",
+            }
+        ],
+    },
+)
+
+engine.run_consolidation()
+result = engine.retrieve_context("How do I fix my django authentication errors?")
+
+print(result.markdown_context)
+print(engine.get_context_trace())
+```
+
+## Tests
+
+Run the memory test suite with:
+
+```bash
+python3 -m unittest discover -s tests -p 'test_*.py'
+```
+
+The current suite covers:
+
+- import boundaries
+- working memory bounds and snapshots
+- episodic log persistence
+- associative node and edge storage
+- vector index ranking
+- hierarchical retrieval and preference recall
+- retrieval trace scoring normalization
+- manual prune and rewrite behavior
+- consolidation creation, update, and watermark behavior
+
+## Not Done Yet
+
+The README should be clear about what is still future scope from the PRDs:
+
+- no CLI, web UI, or phone companion is implemented yet
+- no always-on background scheduler for inactivity-based consolidation yet
+- no cross-device sync yet
+- no multi-repo memory sharing yet
+- no full agent orchestration loop yet
+- no secure remote execution layer yet
+
+## Development Notes
+
+- The code is organized to keep memory logic decoupled from future UI or agent layers.
+- Tests use dependency injection heavily so memory behavior can be verified without external services.
+- The local-first constraint from the PRDs is preserved in the package design: raw logs, structured memory, and vector lookup are intended to live on the user machine.
+
+./.venv/bin/python -m core.runtime.web sample-test

devenv_ai-0.1.0/core/__init__.py

@@ -0,0 +1 @@
+

devenv_ai-0.1.0/core/ai/__init__.py

@@ -0,0 +1,4 @@
+from .engine import AICore
+from .models import AIResponse, ToolCallRequest
+
+__all__ = ["AICore", "AIResponse", "ToolCallRequest"]