XF/GIA
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Increase platform abstraction cohesion

Browse Source
This commit is contained in:
Mark Veidemanis
2026-03-06 17:47:58 +00:00
parent 438e561da0
commit 8c091b1e6d
55 changed files with 6555 additions and 440 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
artifacts/mcp/manticore-mcp-server.md Normal file
View File

@@ -0,0 +1,71 @@
# Manticore MCP Server (GIA)
This document describes the MCP server wired for task + memory operations in GIA.
## Server entrypoint
- Django management command: `python manage.py mcp_manticore_server`
- Python module: `core.mcp.server`
- Tool handlers: `core.mcp.tools`
## Rust worker frontend (optional)
For low-overhead direct Manticore operations, a Rust stdio MCP worker is included:
- Project: `rust/manticore-mcp-worker`
- Build: `make mcp-rust-build`
- Binary: `rust/manticore-mcp-worker/target/release/manticore-mcp-worker`
- VS Code server name: `manticore-rust-worker` (disabled by default in `/code/xf/.vscode/mcp.json`)
This worker exposes fast table/status/query/maintenance operations and can be enabled when you want a minimal MCP process in front of Manticore.
## VS Code wiring
Workspace config is in `/code/xf/.vscode/mcp.json`:
- Server name: `manticore`
- Launch method: `podman exec -i ur_gia /venv/bin/python manage.py mcp_manticore_server`
- Forced env:
- `MEMORY_SEARCH_BACKEND=manticore`
`MANTICORE_HTTP_URL` is inherited from container environment so each deployment can set the correct reachable address.
This allows MCP tool calls from VS Code to run against the live GIA container without requiring local Django dependencies.
## Implemented MCP tools
- `manticore.status`
- `manticore.query`
- `manticore.reindex`
- `memory.list`
- `memory.propose`
- `memory.pending`
- `memory.review`
- `memory.suggest_from_messages`
- `tasks.list`
- `tasks.search`
- `tasks.get`
- `tasks.events`
- `tasks.create_note`
- `tasks.link_artifact`
- `wiki.create_article`
- `wiki.update_article`
- `wiki.list`
- `wiki.get`
- `project.get_guidelines`
- `project.get_layout`
- `project.get_runbook`
- `docs.append_run_note`
`docs.append_run_note` appends markdown notes to `/tmp/gia-mcp-run-notes.md` by default (or a project path you pass explicitly).
All MCP tool invocations are audit-logged in `core_mcptoolauditlog` (`MCPToolAuditLog` model).
## Runtime notes
1. Ensure GIA services are running (`make run`).
2. Start Manticore container:
- `./utilities/memory/manage_manticore_container.sh up`
3. Optional initial index:
- `podman exec ur_gia /venv/bin/python manage.py memory_search_reindex --user-id <id> --statuses active`
4. In VS Code, approve/enabled the workspace MCP server when prompted.

28
artifacts/plans/11-personal-ai-memory.md
View File

@@ -1,28 +0,0 @@
# Feature Plan: Personal AI Memory (Per Person)
## Goal
Store and manage long-lived person-specific memory for better continuity and assistant quality.
## Why This Fits GIA
- Person-centric data model already exists.
- Current approvals pattern can gate memory writes.
## Scope
- Memory entries: preferences, commitments, facts, communication style.
- Confidence/expiry fields and provenance links.
- Approval-required writes with edit/delete controls.
## Implementation
1. Add memory model linked to `Person` with source references.
2. Add extraction pipeline (suggested memory from messages).
3. Add approval queue for memory create/update/delete.
4. Add retrieval service for compose/AI workspace prompts.
5. Add memory hygiene jobs: stale decay, contradiction detection.
## Acceptance Criteria
- Every memory has provenance and last-verified timestamp.
- Unapproved memory never influences generated output.
- Users can inspect, edit, and purge memory entries.
## Out of Scope
- Cross-user shared memory graph.

60
artifacts/plans/12-mcp-server-for-tasks-and-knowledge.md
View File

@@ -1,60 +0,0 @@
# Feature Plan: MCP Server for Tasks + Wiki/Knowledgebase
## Goal
Create an MCP server that allows agents to:
- read/write task context,
- create/update knowledgebase/wiki artifacts during task execution,
- retrieve coding guidelines/project layout for continuity between runs.
## Why This Fits GIA
- Tasks, approvals, and command-driven automation already exist.
- This provides durable agent memory and operator visibility of "what changed, why, and how to use it".
## Scope
- MCP server with authenticated tools for:
- `tasks.list`, `tasks.get`, `tasks.search`, `tasks.events`
- `tasks.create_note`, `tasks.link_artifact`
- `wiki.create_article`, `wiki.update_article`, `wiki.list`, `wiki.get`
- `project.get_layout`, `project.get_guidelines`, `project.get_runbook`
- Permission model tied to user and chat/project scope.
- Audit log for all MCP tool calls.
## Proposed Data Additions
- `KnowledgeArticle` (title, slug, markdown, tags, status, owner, related_task).
- `KnowledgeRevision` (article, revision, author/tool, diff, created_at).
- Optional `TaskArtifactLink` (task, kind, uri/path, summary).
## Implementation
1. Build MCP server process (Python) with JSON-RPC transport and token auth.
2. Implement task read tools against existing task models/views.
3. Implement wiki CRUD tools with revision history.
4. Implement project context tools that read:
- `AGENTS.md`,
- coding standards docs,
- key architecture docs.
5. Add agent-run convention:
- on task start: fetch task + related wiki + guidelines,
- during run: append execution notes,
- on completion: publish "what was done / how to use" article and link to task.
6. Add web UI page for knowledge articles and task-linked docs.
7. Add approvals for destructive knowledge actions (delete/overwrite).
## Acceptance Criteria
- Agent can fetch full task context in one MCP call sequence.
- Agent can publish/update wiki pages tied to tasks.
- Operators can open a task and see linked implementation notes + usage docs.
- MCP actions are fully auditable and scoped by user permissions.
## Security and Guardrails
- Tool-level RBAC and per-user scoping.
- Redact secrets from returned context.
- Rate limits and request signing for external agent clients.
## Rollout
1. Read-only task tools.
2. Wiki write tools with revisioning.
3. Task artifact linking + UI surfaces.
4. Agent workflow templates and docs.
## Out of Scope
- Autonomous code execution from MCP itself.

16
artifacts/plans/13-edit-delete.md
View File

@@ -1,16 +0,0 @@
Perfect, so it all works?
the message saying "the recipient does the same" has been reacted to with a heart but it is not shown in web compose
I also sent an erronrous message, a literal reply to a message that i said i would react to with a heart. the message contained a heart emoji, so it is a reply with a heart and not a reaction
after some confusion I deleted this message
can deleted messages be noted and collected for storage in a deleted message tab in compose that lists what each recipient deleted and when
ensure message edit history is shown, and preserved if the message is deleted, seamlessly reusing the navigation code to preserve a unified interface
work on implementing edit message tracking and delete message indications
consider how to implement

2
artifacts/plans/14-security-audit.md
View File

@@ -1,2 +0,0 @@
# 14) Run security audit using artifacts/1-initial.json. Generated using ship-safe.
https://github.com/asamassekou10/ship-safe

19
artifacts/plans/15-simplify-task-settings-and-more.md
View File

@@ -1,19 +0,0 @@
No Tasks Yet
This group has no derived tasks yet. To start populating this view:
Open Task Settings and confirm this chat is mapped under Group Mapping.
Send task-like messages in this group, for example: task: ship v1, todo: write tests, please review PR.
Mark completion explicitly with a phrase + reference, for example: done #12, completed #12, fixed #12.
Refresh this page; new derived tasks and events should appear automatically.
task settings sound complicated, make them simpler
--
# https://gia.zm.is/settings/system/
assume the user cannot access the log
Use a trace id from the dropdown (recent traces), Event Ledger Smoke `sample[].trace_id`, or UR logs.

34
artifacts/plans/16-agent-knowledge-memory-foundation.md
View File

@@ -1,34 +0,0 @@
# Feature Plan: Agent Knowledge Memory Foundation (Pre-11/12)
## Goal
Establish a scalable, queryable memory substrate so wiki and MCP features can rely on fast retrieval instead of markdown-file scans.
## Why This Comes Before 11/12
- Plan 11 (personal memory) needs performant retrieval and indexing guarantees.
- Plan 12 (MCP wiki/tools) needs a stable backend abstraction independent of UI and tool transport.
## Scope
- Pluggable memory search backend interface.
- Default Django backend for zero-infra operation.
- Optional Manticore backend for scalable full-text/vector-ready indexing.
- Reindex + query operational commands.
- System diagnostics endpoints for backend status and query inspection.
## Implementation Slice
1. Add `core/memory/search_backend.py` abstraction and backends.
2. Add `memory_search_reindex` and `memory_search_query` management commands.
3. Add system APIs:
- backend status
- memory query
4. Add lightweight Podman utility script for Manticore runtime.
5. Add tests for diagnostics and query behavior.
## Acceptance Criteria
- Memory retrieval works with `MEMORY_SEARCH_BACKEND=django` out of the box.
- Switching to `MEMORY_SEARCH_BACKEND=manticore` requires only env/config + container startup.
- Operators can verify backend health and query output from system settings.
## Out of Scope
- Full wiki article model/UI.
- Full MCP server process/tooling.
- Embedding generation pipeline (next slice after backend foundation).

25
artifacts/plans/16-memory-backend-evaluation.md
View File

@@ -1,25 +0,0 @@
# Memory Backend Evaluation: Manticore vs Alternatives
## Decision Summary
- **Recommended now:** Manticore for indexed text retrieval and future vector layering.
- **Default fallback:** Django/ORM backend for zero-infra environments.
- **Revisit later:** dedicated vector DB only if recall quality or ANN latency requires it.
## Why Manticore Fits This Stage
- Already present in adjacent infra and codebase history.
- Runs well as a small standalone container with low operational complexity.
- Supports SQL-like querying and fast full-text retrieval for agent memory/wiki content.
- Lets us keep one retrieval abstraction while deferring embedding complexity.
## Tradeoff Notes
- Manticore-first gives immediate performance over markdown scans.
- For advanced ANN/vector-only workloads, Qdrant/pgvector/Weaviate may outperform with less custom shaping.
- A hybrid approach remains possible:
- Manticore for lexical + metadata filtering,
- optional vector store for semantic recall.
## Practical Rollout
1. Start with `MEMORY_SEARCH_BACKEND=django` and verify API/command workflows.
2. Start Manticore container and switch to `MEMORY_SEARCH_BACKEND=manticore`.
3. Run reindex and validate query latency/quality on real agent workflows.
4. Add embedding pipeline only after baseline lexical retrieval is stable.

95
artifacts/plans/17-person-enrichment-without-llm.md Normal file
View File

@@ -0,0 +1,95 @@
# Feature Plan: Person Model Enrichment (Non-LLM First)
## Goal
Populate `Person` fields from existing message history without spending OpenAI tokens by default:
- `summary`
- `profile`
- `revealed`
- `likes`
- `dislikes`
- `sentiment`
- `timezone`
- `last_interaction`
## Problem We Are Solving
- We have high-volume message data but limited durable person intelligence.
- LLM analysis is expensive for continuous/background processing.
- We need fast, deterministic extraction first, with optional semantic ranking.
## Design Decisions
1. Config scope:
- global defaults
- optional group-level overrides
- per-user overrides
2. Resolution order:
- `user > group > global`
3. Global toggle:
- hard kill-switch (`PERSON_ENRICHMENT_ENABLED`)
4. Per-user/group controls:
- enable/disable enrichment
- write mode (`proposal_required` or `direct`)
- confidence threshold
- max messages scanned per run
- semantic-ranking toggle
## Proposed Data Additions
- `PersonEnrichmentSettings`:
- scope fields (`user`, optional `group`)
- toggle/threshold/runtime limits
- `PersonSignal`:
- normalized extracted clue
- source references (message ids/events)
- confidence and detector name
- `PersonUpdateProposal`:
- pending/approved/rejected person field updates
- reason and provenance
- Optional `PersonFieldRevision`:
- before/after snapshots for auditability
## Processing Flow
1. Select message window:
- recent inbound/outbound messages per person/service
- bounded by configurable caps
2. Fast extraction:
- deterministic rules/regex for:
- timezone cues
- explicit likes/dislikes
- self-revealed facts
- interaction-derived sentiment hints
3. Semantic ranking (optional):
- use Manticore-backed similarity search for classifier labels
- rank candidate signals; do not call OpenAI in default path
4. Signal aggregation:
- merge repeated evidence
- decay stale evidence
- detect contradictions
5. Apply update:
- `proposal_required`: create `PersonUpdateProposal`
- `direct`: write only above confidence threshold and with no conflict
6. Persist audit trail:
- record detector/classifier source and exact message provenance
## Field-Specific Policy
- `summary/profile`: generated from stable high-confidence aggregates only.
- `revealed`: only explicit self-disclosures.
- `likes/dislikes`: require explicit statement or repeated pattern.
- `sentiment`: rolling value with recency decay; never absolute truth label.
- `timezone`: explicit declaration preferred; behavioral inference secondary.
- `last_interaction`: deterministic from most recent message timestamps.
## Rollout
1. Schema and settings models.
2. Deterministic extractor pipeline and commands.
3. Proposal queue + review flow.
4. Optional Manticore semantic ranking layer.
5. Backfill job for existing persons with safe rate limits.
## Acceptance Criteria
- Default enrichment path runs with zero OpenAI usage.
- Person updates are traceable to concrete message evidence.
- Config hierarchy behaves predictably (`user > group > global`).
- Operators can switch between proposal and direct write modes per scope.
## Out of Scope
- Cross-user shared person graph.
- Autonomous LLM-generated profile writing as default.